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Preface 



Manual Objectives 

The RSX-llM-PLUS Utilities Manual is a reference manual describing the use of 15 utilities 
supported on the RSX-llM-PLUS operating system. 

Intended Audience 

This manual is for all users of the RSX-llM-PLUS operating system. 

Structure of This Document 

Chapter 1 describes briefly each of the utilities, and it explains how to enter command lines 
and how to invoke and use the utilities. 

Chapter 2 describes the Bad Block Locator Utility (BAD). 

Chapter 3 describes the Backup and Restore Utility (BRU). 

Chapter 4 describes the File Compare Utility (CMP). 

Chapter 5 describes the File Dump Utility (DMP). 

Chapter 6 describes the Disk Save and Compress Utility Program (DSC). 

Chapter 7 describes the Line Text Editor (EDI). 

Chapter 8 describes the File Transfer Utility Program (FLX). 

Chapter 9 describes the Disk Volume Formatter Utility (FMT). 

Chapter 10 describes the Librarian Utility Program (LBR). 

Chapter 11 describes the Object Module Patch Utility (PAT). 

Chapter 12 describes the Peripheral Interchange Program (PIP). 

Chapter 13 describes the Source Language Input Program (SLP). 

Chapter 14 describes the File Structure Verification Utility (VFY). 

Chapter 15 describes the Task/File Patch Program (ZAP). 
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Appendix A is a summary of the commands and switches for the utilities. 

Appendix B describes the Cross-Reference Processor (CRF). 

Appendix C describes the Data Terminal Emulator (DTE) and the Micro/RSX File Transfer 
Utility (MET). 

Associated Manuals 

The RSX-llM-PLUS MCR Operations Manual describes the Monitor Console Routine (MCR) and 
its commands. The utilities are usually invoked from MCR. This manual uses MCR to specify 
the formats and examples of the utilities. 

The RSX-llM-PLUS Command Language Manual describes the DIGITAL Command Language 
(DCL) and its commands. Some of the utilities can be invoked from DCL. This manual provides 
background information about DCL. 

Conventions Used in This IVIanual 

The following conventions are used in this manual: 



Convention 



Meaning 



> 



MCR> 
DCL> 

XXX > 

UPPERCASE 
command abbreviations 



A right angle bracket is the default prompt for the Monitor 
Console Routine (MCR), which is one of the command interfaces 
used on RSX-llM-PLUS systems. All systems include MCR. 

A dollar sign followed by a space is the default prompt of 
the DIGITAL Command Language (DCL), which is one of the 
command interfaces used on RSX-llM-PLUS and Micro/RSX 
systems. Many systems include DCL. 

This is the explicit prompt of the Monitor Console Routine 
(MCR). 

This is the explicit prompt of the DIGITAL Command Language 
(DCL). 

Three characters followed by a right angle bracket indicate the 
explicit prompt for a task, utility, or program on the system. 

Uppercase letters in a command line indicate letters that must be 
entered as they are shown. For example, utility switches must 
always be entered as they are shown in format specifications. 

Where short forms of commands are allowed, the shortest form 
acceptable is represented by uppercase letters. The following 
example shows the minimum abbreviation allowed for the DCL 
command DIRECTORY: 

$ DIR 
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Convention 



Meaning 



lowercase 



/keyword, 
/qualifier, 
or 
/switch 

parameter 



[option] 



1-] 



() 
:argument 

() 



Any command in lowercase must be substituted for. Usually 
the lowercase word identifies the kind of substitution expected, 
such as a filespec, which indicates that you should fill in a file 
specification. For example: 

filename .type ; version 

This command indicates the values that comprise a file spec- 
ification; values are substituted for each of these variables as 
appropriate. 

A command element preceded by a slash (/) is an MCR 
keyword; a DCL qualifier; or a task, utility, or program switch. 

Keywords, qualifiers, and switches alter the action of the 
command they follow. 

Required command fields are generally called parameters. The 
most common parameters are file specifications. 

Square brackets indicate optional entries in a command line or 
a file specification. If the brackets include syntactical elements, 
such as periods ( . ) or slashes ( / ), those elements are required 
for the field. If the field appears in lowercase, you are to 
substitute a valid command element if you include the field. 
Note that when an option is entered, the brackets are not 
included in the command line. 

Square brackets around a comma and an ellipsis mark indicate 
that you can use a series of optional elements separated 
by commas. For example, (argument[,...]) means that you 
can specify a series of optional arguments by enclosing the 
arguments in parentheses and by separating them with commas. 

Braces indicate a choice of required options. You are to choose 
from one of the options listed. 

Some parameters and qualifiers can be altered by the inclusion 
of arguments preceded by a colon. An argument can be either 
numerical (COPIES:3) or alphabetical (NAME:QIX). 

Parentheses are used to enclose more than one argument in a 
command line. For example: 

SET PROT = (S:RWED,0:RWED) 

Commas are used as separators for command line parameters 
and to indicate positional entries on a command line. Positional 
entries are those elements that must be in a certain place in the 
command line. Although you might omit elements that come 
before the desired element, the commas that separate them must 
still be included. 
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Convention Meaning 



[g,m] The convention [g,m] signifies a User Identification Code (UIC). 

[directory] The g is a group number and the m is a member number. The 

UIC identifies a user and is used mainly for controlling access 
to files and privileged system functions. 

This may also signify a User File Directory (UFD), commonly 
called a directory. A directory is the location of files. 

Other notations for directories are: [ggg,mmm], [gggmmm], [ufd], 
[name], and [directory]. 

The convention [directory] signifies a directory. Most directories 
have 1- to 9-character names, but some are in the same [g,m] 
form as the UIC. 

Where a UIC, UFD, or directory is required, only one set of 
brackets is shown (for example, [g,m]). Where the UIC, UFD, 
or directory is optional, two sets of brackets are shown (for 
example, [[g,m]]). 

filespec A full file specification includes device, directory, file name, file 

type, and version number, as shown in the following example: 

DL2 : [46 , 63] INDIRECT . TXT ; 3 

Full file specifications are rarely needed. If you do not provide 
a version number, the highest numbered version is used. If 
you do not provide a directory, the default directory is used. 
Some system functions default to particular file types. Many 
commands accept a wildcard character (*) in place of the file 
name, file type, or version nvimber. Some commands accept a 
filespec with a DECnet node name. 

A period in a file specification separates the file name and file 
type. When the file type is not specified, the period may be 
omitted from the file specification. 

; A semicolon in a file specification separates the file type from 

the file version. If the version is not specified, the semicolon 
may be omitted from the file specification. 

@ The at sign invokes an indirect command file. The at sign 

immediately precedes the file specification for the indirect 
command file, as follows: 



Of llename [ . type ; Tersion] 
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Convention 



Meaning 



A horizontal ellipsis indicates the following: 

• Additional, optional arguments in a statement have been 
omitted. 

• The preceding item or items can be repeated one or more 
times. 

• Additional parameters, values, or other information can be 
entered. 

A vertical ellipsis shows where elements of command input or 
statements in an example or figure have been omitted because 
they are irrelevant to the point being discussed. 



KEYNAME 
"print" and "type" 

black ink 
red ink 



|CTRL/a| 



This tjqjeface denotes one of the keys on the terminal keyboard. 
For example, the RETURN key. 

The term "print" refers to any output sent to a terminal by 
the system. The term "type" refers to any user input from a 



the system. The term "t5^e" refers to any user input 
terminal. 

In examples, what the system prints or displays is printed in 
black. 

In interactive examples, what the user types is printed in red. 
System responses appear in black. 

A symbol with a 1- to 3-character abbreviation, such as Eor 
I RET I , indicates that you press a key on the terminal. For example, 
[rItI indicates the RETURN key, M\ indicates the LINE FEED key, 
and [Ml indicates the DELETE key. 



The symbol Ictrl/o| means that you are to press th e key marked 
CTRL while pressing another key. Thus, I ctrl/z I indicates that 
you are t o press the CTRL key and the Z key together in this 
fashion. I ctrl/z l is echoed on some terminals as 'Z. However, 
not all control characters echo. 
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Summary of Technical Changes 



The following sections list features, commands, qualifiers, error messages, and restrictions that 
are new to the utilities or have been modified for the RSX-llM-PLUS Version 4.0 operating 
systems. These new or modified features are documented in this revision of the RSX-llM-PLUS 
Utilities Manual 

Also, major changes to the organization of the manual are included at the end of this summary. 

New Hardware Support 

RSX-llM-PLUS Version 4.0 supports the following new hardware: 

MicroPDP-11/53 processor 

DHQll 16-line multiplexer 

CXA16/CXB16 16-line multiplexer 

CXY08 8-line multiplexer 

DELUA UNIBUS synchronous communications controller 

RX33 diskette drive 

RA82, RD31, RD32, RD53, and RD54 disk drives 

TU81 and TU81E 9-track magnetic tape drives 

TK70 and TK50 cartridge tape drives 

LA75 printer 

DFAOl modem 
For FLX, the new RT-11 devices are as follows: 

RX33 and RX50 diskettes 

RD50 and RD51 disks 

RC25 and RCF25 fixed/removable disks 
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New or Modified Features 

BRU has the following new or modified features: 

• BRU detects and automatically skips over a bootable system image when appending to or 
restoring from a magnetic tape. 

• Access to a device allocated and mounted by another user is no longer allowed. 

• A method of executing indirect command files containing BRU commands is described. 

• The defaults for wildcard ( * ) file specifications have been changed. 

For FLX, file type CDA has been added to the list of default file types for the Image Mode 
switch (/IM). 

For FMT, DL-type devices can be used with the /WLT and /VE switches. 
LBR has the foUowdng new and modified features: 

• A description of the user file attributes is included. 

• LBR now recognizes lowercase and uppercase characters in macro directives. 

New and IVIodified Qualifiers and Switches 

BRU has the following new and modified qualifiers: 

• The /IDENTinCATION qualifier displays the version of BRU in use. 

• The /LENGTH qualifier should not be used with cartridge tape devices such as the TK25 
and TK50. 

• The description of the /NOSUPERSEDE qualifier has been expanded. 

• The description of the /VERIFY qualifier has been changed. 

The new DMP switch /LIM:n:m specifies the range of bytes n to m of each record or block to 
be dumped. 

New or IVIodified Error Messages 

BRU produces the following new and modified error messages: 

• The following new error messages are displayed when the mount status of the input and/or 
output devices is inconsistent with the qualifiers specified: 

BRU -- *FATAL* — Device not moimted foreign on ddnn 
BRU -- *FATAL* — Device not mounted files 11 on ddnn 

• The following new message is displayed if an append operation is attempted on a tape 
other than the first: 

BRU — *FATAL* — Cannot append on continuation volume 
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Restrictions 

BRU has the following restrictions: 

• The /NEW_VERSION and /VERIFY qualifiers are mutually exclusive. They cannot be 
specified together in the same command line. 

• You must specify /REWIND/APPEND when placing the first backup set on a magnetic 
tape that contains a bootable system image 

• The /TAPE —LABEL qualifier is ignored during a restore operation if there is a bootable 
system image at the beginning of the tape 

• Do not run BRU and BAD simultaneously when using standalone BRU (BRUSYS). 

Changes to tlie Document 

The following changes in organization and additions to the document have occurred: 

• The chapters on the utilities have been alphabetized according to 3-character utility names. 
Chapter 1 is an introductory chapter. 

• Appendix C, which describes the Data Terminal Emulator (DTE) and the Micro/RSX File 
Transfer Utility (MFT), has been added. 
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Chapter 1 

Introduction 

The RSX-llM-PLUS operating system provides several kinds of utilities for your use. Utilities 
are programs that allow you to work with different kinds of files and the contents of those 
files, and they also allow you to work with different kinds of media (such as disks, magnetic 
tapes, and cassettes). The RSX-llM-PLUS utility programs are listed and described briefly in 
the next section; reference information for each utility is presented as a separate chapter of this 
manual. Three appendixes are also included to provide you with a summary of commands 
and switches for the utilities; to describe the Cross-Reference Processor (CRF), which is used 
with the MACRO-11 assembler (MAC) and the Task Builder (TKB); and to describe the Data 
Terminal Emulator (DTE) and the Micro/RSX File Transfer Utility (MFT). 

In addition to summarizing the RSX-llM-PLUS utilities, this introduction provides the following 
information: 

• Describes how to enter RSX-llM-PLUS command lines and file specifications (Sections 1.2 
and 1.3) 

• Describes how to invoke utilities and enter command lines to them (Section 1.4) 

• Describes how to use indirect command files (Section 1.5) 

1 . 1 RSX- 1 1 M-PLUS Utility Programs 

This manual provides reference information for the following RSX-llM-PLUS utilities: 

• Bad Block Locator UtiUty (BAD) 

• Backup and Restore Utility (BRU) 

• File Compare Utility (CMP) 

• File Dump Utility (DMP) 

• Disk Save and Compress Utility (DSC) 

• Line Text Editor (EDI) 

• File Transfer Utility Program (FLX) 

• Disk Volume Formatter Utility (FMT) 
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Librarian Utility Program (LBR) 

Object Module Patch Utility (PAT) 

Peripheral Interchange Program (PIP) 

Source Language Input Program (SLP) 

File Structure Verification Utility (VFy) 

Task/File Patch Program (ZAP) 

The following sections briefly describe each utility. 

Note that the utilities described in this manual are not the only programs on RSX-llM-PLUS 
operating systems that are used as or considered to be utilities. The Task Builder (TKB), 
Crash Dump Analyzer (CD A), and MACRO-11 assembler (MAC) are examples of other utility- 
like programs. Some programs, such as the DIGITAL standard editor (EDT), are common 
across different operating systems. These other programs are documented elsewhere in the 
RSX-llM-PLUS documentation set. Refer to the RSX-llM-PLUS Information Directory and 
Master Index for information on what programs are available and where they are described. 

1.1.1 Bad Block Locator Utility 

BAD determines the number and location of bad blocks on a volume. The information gathered 
from running BAD on a volume can be used in different ways when that volume is initialized. 

1.1.2 Baclcup and Restore Utility 

BRU transfers files from a Files-11 volume to one or more backup volumes (including non- 
Files-11 volumes) and retrieves files from the backup volume (or volumes). BRU is faster than 
DSC in most areas. Also, BRU compresses data, the volumes do not have to be initialized, and 
incremental backups are possible. BRU can be run either on line or stand alone. 

1.1.3 File Compare Utility 

CMP compares two text files, record by record, and lists the differences between the two files. 

1.1.4 File Dump Utility 

DMP is a file listing program that allows you to examine the contents of a file or volume of 
files. DMP also provides options that control the format of the contents. 

1.1.5 Disk Save and Compress Utility 

DSC copies Files-11 disk files to disk or tape and from DSC-created tape back to disk. While 
copying the files, DSC also consolidates the data storage area and vrates files in contiguous 
blocks unless it encounters a bad block. 

1.1.6 Line Text Editor 

EDI is a line-oriented, interactive editor used to create and maintain text and source files. (The 
RSX-llM-PLUS Guide to Program Development gives specific information about using EDI to 
create and maintain program source files.) 
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1.1.7 File Transfer Utility Program 

FLX is a file transfer and format conversion program that transfers files between DOS-11, 
RT-11, and Files-11 volumes, with some restrictions. 

1.1.8 Dlsl< Volume Formatter Utility 

FMT formats and verifies several types of disks. FMT writes and verifies sector headers, sets 
the density for flexible disks, and allows spawning of BAD. 

1.1.9 Librarian Utility Program 

LBR is a library maintenance program that creates, displays, and modifies library files. LBR can 
process macro, object, and universal libraries. 

1.1.10 Object iS/lodule Patcli Utility 

PAT updates, or patches, relocatable binary object modules. 

1.1.11 Perlptieral Interctiange Program 

PIP copies files and performs several file control functions, such as concatenating, renaming, 
spooling, listing, deleting, and unlocking. 

1.1.12 Source Language Input Program 

SLP is a noninteractive editing program that is used to maintain and audit source files. 

1.1.13 File Structure Verification Utility 

VFY is a disk verification program that verifies the consistency and validity of the file structure 
on a Files-11 volume. 

1.1.14 Task/File Patch Program 

ZAP is a patch utility that examines and directly modifies locations in a task image file or data 
file. 

1.2 Command Lines 

The general format for command lines in most of the RSX-llM-PLUS utilities is shown next. 

Format 

outfile[,...]=infile[,...] 

The variables outfile and infile are file specifications for the output and input files to be operated 
on by the utility. (File specifications are described in Section 1.3.) 

Note 

This general format varies from utility to utility. Some utilities use the entire 
command line and others use abbreviated forms of the command line. For some 
other utilities (such as BRU), the format is different. The syntax for each utility 
is described in the chapter that describes that utility. 
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Most of the utilities also accept indirect command files containing command lines to the utility, 
as described in Section 1.5. 

1 .3 File Specifications 

In the command line format described in Section 1.2, outfile and infile represent file specifications. 
The number of file specifications you can enter depends on the utility. The maximum terminal 
line length depends on the size of the output buffer for your terminal (the default length is 
80 characters). 

The format for entering file specifications is shown next. 

Format 

ddnn:[directory]filename.type;version[/switch[...]/subswitch[...]] 

Parameters 

ddnn 

Specifies the physical or logical device unit containing the desired volume. The name 
consists of two American Standard Code for Information Interchange (ASCII) characters 
followed by an optional 1-, 2-, or 3-digit octal number and a colon (:) (for example, DM0: 
or TT116:). 

The default is the user's system device, SYG. 

directory 

Specifies the directory containing the desired file or files. The directory can have two 
possible formats. The named directory format has one to nine of the following characters: 
the 26 letters A to Z and the numbers zero to nine (for example, [USERl]). The numbered 
directory (sometimes referred to as the User Identification Code (UIC) or the User File 
Directory (UFD)) format has two numbers separated by a comma (for example, [g,m]). The 
variables g and m are octal numbers from to 377 that represent the group and member 
numbers, respectively, of the file's owner. 

The default is the current directory to which your terminal is set. 

See the RSX-llM-PLUS MCR Operations Manual or the RSX-UM-PLUS Command Language 
Manual for more information on directories. 

filename 

Specifies the name of the file. File names can be from one to nine characters in length. 
There is no default. 

type 

Specifies the file type of the file. The file type provides a convenient means for distinguishing 
different forms of the same file. For example, a FORTRAN source program file might be 
named COMP.FTN and the object file for the same program might be named COMP.OBJ. 
In this way, the file type identifies the nature of the contents of the file. 

The file type and file name are separated by a period ( . ). The file type may not be specified 
or can be up to three alphanumeric characters in length. The default for a file t)rpe depends 
on the utility or task you are working with and if the file is an input or output file. 
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See the RSX-llM-PLUS MCR Operations Manual or the RSX-UM-PLUS Command Language 
Manual for a list of standard file types. 

version 

Spedfies a decimal (or octal if this option was chosen during system generation) number 
that spedfies different versions of the same file. For example, when a file is created, it is 
assigned a version number of 1 by default. Thereafter, each time the file is revised and 
unless you specify otherwise, the file system creates a new file with the same file name and 
file type, but with a version number incremented by 1. Version numbers range from 1 to 
32767\o. However, some utilities allow the use of to specify the highest numbered version 
and -1 to spedfy the lowest numbered version (0, or the latest version, is the default). If a 
file has a version number of 32767-yo, no more versions of it can be created. 

Version number and file t5^e are separated by a semicolon (;). The default is the latest 
version. 

switch 

Spedfies an ASCII name specifying a switch (or qualifier in BRU) associated with a function 
to be executed by the utility. Most utility functions are implemented by means of switches 
and subswitches. Switches can take one of the following three forms: 

Switch 

Format Meaning 

/sw Invokes the switch function. 

/-sw Negates the switch function. 

/NOsw Negates the switch function. 

Switches can also take values in the form of ASCII strings and numeric strings. The values 
modify the function of the switch. 

Most numeric values are octal by default. To spedfy a decimal number, terminate the 
number with a decimal point. Values preceded by a number sign ( # ) are octal; this optional 
notation provides explicit specification of octal values. Any number can be preceded by 
either a plus ( + ) or minus (-) sign; plus is the default. Where explicit octal notation (#) is 
used, the sign, if spedfied, must precede the number sign ( # ). 

The following are examples of valid switch specifications: 

/SW:27.:MAP:29. 

/-SW 

/NOSW: -#50: SWITCH 

subswitch 

Specifies an ASCII name specifying a subswitch associated with a switch. Subswitches 
provide a subset of functions related to the main switch function. The following is an 
example of a subswitch specification: 

PIP> [200 , 200] * . * ; */PR/FO 

In the previous command line, /FO is a subswitch applied to the /PR switch. 
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Syntactically, subswitches are identical to switches. The rules for entering switches also 
apply for entering subswitches. 

1 .4 Invoking the Utilities 

You invoke a utility from the command line interpreter (CLI) environment. The CLI can be the 
Monitor Console Routine (MCR), the DIGITAL Command Language (DCL), or an alternate user- 
vmtten CLI. For more information on MCR, see the RSX-llM-PLUS MCR Operations Manual. 
For more information on DCL, see the RSX-llM-PLUS Command Language Manual 

To determine whether you are using MCR or DCL or another CLI, press CTRL/C, which returns 
the explicit monitor prompt: 

MCR> 

or 

DCL> 

or 

CLI> 

You can work with a utility directly (interactively) or by means of indirect command files. For 
systems in which all utilities are installed, you can use any of three methods to invoke a utility. 
Section 1.4.1 describes these methods. For systems in which not all utilities are installed, you 
can use the method described in Section 1.4.2. 

Section 1.5 describes how to invoke a utility that can then accept commands from an indirect 
command file. 

You can invoke a utility when MCR or DCL prompts you. The MCR prompt is as follows: 

> 

If you press CTRL/C first, the MCR prompt is as follows: 

MCR> 

The DCL prompt is shown next. 

$ 

If you press CTRL/C first, the DCL prompt is as follows: 

DCL> 

In MCR, the utilities are always invoked by their 3-character names. DCL, however, has 
commands that access utilities transparently to the user. You do not have to explicitly specify 
the utility to use it. For example, the DCL command DIFFERENCES invokes the File Compare 
Utility (CMP); and the DCL commands COPY, DELETE, and PURGE invoke the Peripheral 
Interchange Program (PIP). This transparent access to utilities covers most common utility needs 
for DCL users. If you use these DCL commands, you should use the general format for 
specifying files shown next. 
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Format 

command[/qualifier[...]] infUe outfile 

For more information on DCL commands and their formats, refer to the RSX-UM-PLUS 
Command Language Manual. 

DCL users can also use all MCR command forms by using the DCL command MCR (or MC) as 
follows: 

$ MCR utilityname |RET| 
utilitynauiie>coinmaaidline |RET| 
utilityname> 

or 

$ MCR utilityname commandline |RET| 

1.4.1 Invoking Installed Utilities 

The RSX-llM-PLUS operating system provided in distribution kits does not have any utilities 
installed. Once the system has been generated, the system manager usually installs any 
commonly used utilities. Use the MCR command TAS or DCL command SHOW TASKS 
/INSTALL to see which utilities are currently installed in the system. If the utility you want to 
use is not installed, any privileged user can install it with the MCR or DCL command INSTALL. 
Once the utility is installed, you can invoke it. 

The following sections describe the three primary methods you can use to invoke installed 
utilities. 

1 .4. 1 . 1 Invoking a Utility and Returning Control to Your CU 

You can use the following command line to invoke a utility, to execute a function, and to return 
control directly to MCR: 

>utilityiiaine commandline |RET| 
> 

You can use the following command line to invoke a utility, to execute a function, and to return 
control directly to DCL: 

$ MCR utilityname commandline |RET| 
$ 

Using this method to invoke the utility allows you to enter a single command for execution. The 
command is executed and control returns to your CLI. (The method described in the following 
section allows you to enter more than one command line because control returns to the utility 
rather than to CLI.) 

Two exceptions to this command format are the SLP and ZAP utilities. UrUess you are using 
indirect command files, you must first invoke these utilities and then enter the command lines 
as described in Section 1.4.1.2. See Section 1.5 for more information on indirect command files. 
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1.4.1.2 Invoking and Passing Control to o Utility 

Use one of the following forms of command lines to invoke an installed utility and pass control 
to it: 

For MCR: 

>utilityname |RET| 

utilitynaine>coiimandline |RET| 
utilityname> 

For DCL: 

$ MCR utilityname |RET| 

utilityiiame>coiiimaiKiline |RET| 
utilit3rna]ne> 

These commands do not execute a function; rather, they make a utility available for execution 
of more than one function without returning control to MCR or DCL. 

To terminate the utility and return control to MCR or DCL, press CTRL/Z. 

Example 

>pip \M] 

PIP> te8t.dat;5/DE [RETI 
PIP> 

1.4.2 Invoking Uninstalled Utilities 

You can use the following method to invoke an uninstalled utility. This method is useful for 
smaller systems on which not all utilities are installed. This method uses either the MCR or 
DCL command RUN to invoke the utility. 

The method invokes the utility by means of the following command: 

>RUN Sutilityname 

or 

$ RUN Sutilityname 

The dollar sign ($) directs MCR or DCL to search the system directory for the utility and to 
bring it into storage. If the utility is not in the system directory, MCR or DCL then searches in 
the library directory and invokes the utility from there. 

When the utility gains control, it displays the following prompt: 

utilitynaiiie> 

Then, it waits for you to enter a command line. The utility continues to prompt you after each 
command line is executed. To terminate the utility, press CTRL/Z. Control is then returned to 
MCR or DCL. 

A variation of this method allows the utility to run under a UIC other than the current UIC, as 
follows: 

For MCR: 

>RUH $utilityname/UIC=[g,m] 
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For DCL: 

$ RUN/UIC: [g,m] Sutilityname 

When the utility gains control, it prompts for functions to execute until you press CTRL/Z. 

1 .5 Using Indirect Command Files 

An indirect command file normally contains a sequence of command lines that are interpreted 
by a task (usually a system-supplied task such as a utility, the MACRO-11 assembler (MAC), 
or the Task Builder (TKB)). These command lines appear in the indirect command file exactly 
as you would enter them from your terminal. 

The command lines contained in the indirect command file are executed when the indirect 
command file is invoked. If you invoke the file from MCR or DCL, each command line must 
begin with the name of the utility or command you want to use. If you invoke the file from 
the utility itself, the command lines do not begin with the name of the utility, but they must 
all be legal for that utility. 

For example, an indirect conraiand file might contain the following series of PIP command lines: 

=DB2 : [303 , 24] TESTPREP . CMD 
TESTPREP . * ; */LI 
TESTPREP. */PU: 2 
* . CMD/SP 

To invoke the indirect command file (PIPCMDS.CMD), enter one of the following sets of 
commands: 

For MCR: 

>PIP OPIPCMDS.CMD [Ml 

For DCL: 

>RUN $PIP [REH 
PIPXDPIPCMDS [RET] 

In this example, PIP is invoked and accesses the file PIPCMDS.CMD, which contains the 
sequence of PIP conunand lines. Because PIP is invoked first, the command lines in the file do 
not have to begin with PIP. PIP executes the command lines and returns control to MCR, DCL, 
or PIP, depending on which command set you use. 

The RSX-llM-PLUS operating system also allows you to use indirect command files that 
contain MCR or DCL commands. The command lines must be legal for the CLI. You invoke 
the indirect command file by entering only the file specification preceded by the at sign (@) 
character in response to the prompt (in this case, the MCR prompt) as follows: 

XHndirectcoimandfile 
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The default values for elements of an indirect command file specification are as follows: 

Element Default Value 

ddnn SYO 

directory The current directory 

filename No default; the file name must be specified 

type CMD 

version The latest version of the file 

For complete information on how to use indirect command files, see the RSX-llM-PLUS Indirect 
Command Processor Manual. 



1-10 Introduction 



Chapter 2 

Bad Block Locator Utility (BAD) 



The Bad Block Locator Utility (BAD) tests disks and DECtapes for the location and number of 
bad blocks. BAD then records this bad block information on the volume. Then you use the 
Monitor Console Routine (MCR) command INI, which allocates the bad blocks to the bad block 
file [0,0]BADBLK.SYS. The bad blocks are marked as in-use and therefore cannot be allocated 
to other files. 

BAD supports any last-track device as well as vendor-supplied cartridges that do not have 
a prerecorded manufacturer's bad-sector file on the last track. You can use BAD in its task 
version, which runs at the same time as other tasks, or in its standalone version included in 
[6,54]BRUSYS.SYS, which runs by itself on the computer. The standalone version is required if 
you have a system with a single disk drive. 

BAD can also be invoked through the Digital Command Language (DCL) command ANALYZE 
/MEDIA. See the RSX-llM-PLUS Command Language Manual for more information. 

2. 1 BAD Command Line 

You can invoke BAD by any of the methods described in Chapter 1. 
The command line for BAD is shown next. 

Format 

ddnn:[/switch[. . .]] 

Parameters 

ddnn 

Specifies a physical device. 

switch 

Specifies an optional switch that qualifies the BAD command line. Multiple BAD switches 
for a device must be specified on one line. If you do not specify any switch, BAD begins 
its pattern checking of individual blocks. 
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Table 2-1 contains a reference list of BAD switches along with a brief description of each. 
For a detailed description of BAD switches see Section 2.2. 

Table 2-1: BAD Switches 



Switch 



Format 



Function 



Allocate /ALO:volumelabel Prompts you for blocks to be allocated to BADBLK.SYS and 

entered in the bad block descriptor file. 

Lists bad blocks as they are located. 

Prompts you for additional bad blocks, which are entered in 
the bad block descriptor file. 

Creates the bad block descriptor file on a last-track device. 

Specifies the doubleword data pattern used to locate bad blocks. 

Recovers soft errors. 

Reads the bad block descriptor file and prompts for input. 



Ust 


/LI 


Manual 


/MAN 


Override 


/OVR 


Pattern 


/PAT=m:n 


Retry 


/RETRY 


Update 


/UPD 



2.2 BAD Switch Descriptions 

The following sections describe the switches you can use with BAD commands. 

2.2.1 Allocate 

The Allocate swdtch (/ALO:volumelabel) prompts you for additional bad blocks that are added 
to the bad block descriptor file and allocated to the bad block file [0,0] BADBLK.SYS. 

Format 

/ALO:volumelabel 

Parameter 

volumelabel 

Specifies the volume. 

The /ALO:volumeIabel switch eliminates the need to reinitialize the disk after updating the bad 
block descriptor file. This sv«tch does not cause BAD to perform pattern checks. 

Note 

To use this switch, the volume must be mounted as a Files-11 device and the 
user must be privileged. 

If you enter bad blocks by using the /ALO:voIumelabel sv^tch, BAD wall prompt you as follows: 

BAD>LBN(S)= 

You may then enter bad blocks in the following format: 
blocknum : number 
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The variable number specifies the number of sequential bad blocks beginning at the specified 
block number, blocknum. The colon ( : ) is required when you specify a sequence of bad blocks 
in this format. Both blocknum and number default to decimal values unless preceded by a 
number sign ( # ), which indicates an octal value. 

Examples 

BAD>LBN(S)=70:3 [Ml 

Enters the block numbers 70, 71, and 72 in the bad block descriptor file. The blocks are 
allocated to the bad block file [0,0]BADBLK.SYS. 

BAD>LBN(S)=3 [M] 

Specifies a single bad block and enters block 3 in the bad block descriptor file. Block 3 is 
allocated to the bad block file [0,0]BADBLK.SYS. 

BAD>LBN(S)= 100:2,3, 200:100 45:1 [Ml 

Enters blocks 100, 101, 3, 200 to 299, and 45 in the bad block descriptor file. These blocks are 
allocated to the bad block file [0,0] BADBLK.SYS. You can separate bad block sequences with a 
space, tab, or comma. 

BAD>LBN(S)=[RET| 

LBNs allocated to BADBLK.SYS = 

004799:001 
000100:002 
000003:001 
000200:001 

LBNs in BAD BLOCK File = 

000100:002 
000003:001 
000200:001 
000045:001 

BAD> LBN(8) = 

Lists all the Logical Block Numbers (LBNs) allocated to BADBLK.SYS before listing the LBNs 
in the bad block descriptor file when a carriage return is entered in response to the prompt. 

LBNs 100, 101, 003, and 200 are allocated to the bad block file [0,0] BADBLK.SYS. 

The previous command line also allocates LBN 4799, which is the LBN for the bad block 
descriptor file on this particular disk. Note that the LBN for the bad block descriptor file does 
not appear in the bad block file. However, this disk has one LBN (LBN 45) that is contained 
in the bad block file but is not yet allocated to the bad block file [0,0] BADBLK.SYS. You can 
now allocate LBN 45 by entering it in response to the LBN(s)= prompt. (The "Duplicate block 
number" message will appear because the LBN already exists in the bad block file.) 

When a bad block sequence is entered, BAD determines if these bad blocks are adjacent to 
an already existing sequence. If you are using a non-last-track device, BAD appends your bad 
block entry to the existing sequence. If you are using a last-track device, BAD records individual 
bad blocks in core memory, but it lists entries at your terminal as part of existing bad block 
sequences. 
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When you have finished supplying information for the /ALOrvolumelabel switch, press the 
ESCAPE key, the ALTMODE key, or CTRL/Z in response to the prompt. The bad block 
descriptor file will then be rewritten with the new bad block information. Blocks that you enter 
manually and that BAD decides are reliable are included in the bad block descriptor file. 

2.2.2 List 

The List switch (/LI) prints all bad blocks by number (in decimal) on your terminal. The bad 
blocks are listed as BAD performs a data pattern check on each block. BAD does not hst 
manually entered blocks that are tested as reliable. The List switch (/LI) is valid for all devices. 

2.2.3 Manual 

The Manual switch (/MAN) first prompts you for bad block information and then performs data 
pattern checking. Any block that you enter by using the Manual switch (/MAN) is included in 
the bad block descriptor file or the Software-Detected Bad Sector File (SDBSF). 

If you enter bad blocks by using the /MAN switch, BAD will prompt you as follows: 

BAD>LBN(S)» 

You may then enter bad blocks in the following format: 

bloclmuni : number 

The variable number specifies the number of sequential bad blocks beginning at the specified 
block number, blocknum. The colon ( : ) is required when you specify a sequence of bad blocks 
in this format. Both blocknum and number default to decimal values unless preceded by a 
number sign ( # ), which indicates an octal value. 

Examples 

BAD>LBN(S)=70:3 [RETI 

Enters the block numbers 70, 71, and 72 in the bad block descriptor file. 

BAD>LBN(S)=3 [RETI 

Specifies a single bad block and enters block 3 in the bad block descriptor file. 

BAD>LBN(S)= 100:2,3, 200:100 45:1 HH] 

Uses both of the previous forms on the same command line. 

This command enters blocks 100, 101, 3, 200 to 299, and 45 in the bad block descriptor file. 
You can separate bad block sequences with a space, tab, or comma. 

When a bad block sequence is entered, BAD determines if these bad blocks are adjacent to 
an already existing sequence. If you are using a non-last-track device, BAD appends your bad 
block entry to the existing sequence. If you are using a last-track device, BAD records individual 
bad blocks in core memory, but it lists entries at your terminal as part of existing bad block 
sequences. 

When you have finished supplying information for the /MAN switch, press the ESCAPE key, 
the ALTMODE key, or CTRL/Z in response to the prompt. Pattern checking wUl then start. 
Blocks that you enter manually and that BAD decides are reliable are included in the bad block 
descriptor file. 
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2.2.4 Override 

The Override switch (/OVR) ignores last track information and writes a bad block descriptor 
file on the last good block before the last track. In other words, the /OVR switch causes BAD 
to treat a last-track device as a non-last-track device. If your device has no bad block file on the 
last track, or if you suspect the reliability of the last track, use the /OVR switch before using 
the MCR command INI. The /OVR switch is valid only for last-track devices. 

Note 

If you use this switch, the /BAI>=[OVR] option for initializing a volume must also be used with 
the INI command to construct the bad block file [0,0]BADBLK.SYS. See the RSX-UM-PLUS 
MCR Operations Manual for a description of the MCR command INI. 

2.2.6 Pattern 

The Pattern switch (/PAT=m:n) locates bad blocks by means of a user-specified doubleword 
data pattern. 

Format 

/PAT=m:n 

Parameter 

m:n 

Represents the two 16-bit octal numbers used as the doubleword data pattern. Decimal 
numbers may be specified by placing a period ( . ) after each number. 

2.2.6 Retry 

The Retry switch (/RETRY) attempts a recovery of hardware errors by means of the device 
driver. This also means that soft errors, such as an ECC (Error Correction Code) correctable 
error, will be recovered and the block will be marked as good. 

The /RETRY switch should be specified when using BAD with DU-type devices. 

2.2.7 Update 

The Update switch (/UPD) reads the bad block descriptor file immediately and prompts for 
additional bad blocks. This switch does not cause BAD to write pattern checks. 

Note 

Updating the bad block descriptor file on file-structured volumes does not cause the bad block 
file [0,0]BADBLK.SYS to be updated. 



Bad Block Locator Utility (BAD) 2-5 



Example 

BAD>LBN(8)=[Bll] 

000100:002 

000003:001 

000200 : 100 

000045:001 

BAD>LBN(S)= 

Lists all the sequences in the bad block descriptor file when a carriage return is entered in 
response to the prompt. 

The first number in the display represents the beginning block of the sequence. The second 
number represents the number of bad blocks. Bad block numbers are listed in decimal. 

When a bad block sequence is entered, BAD determines if these bad blocks are adjacent to 
an already existing sequence. If you are using a non-last-track device, BAD appends your bad 
block entry to the existing sequence. If you are using a last-track device, BAD records individual 
bad blocks in core memory, but it lists entries at your terminal as part of existing bad block 
sequences. 

When you have finished supplying information for the /UPD switch, press the ESCAPE key, 
ALTMODE key, or CTRL/Z in response to the prompt. The bad block descriptor file will then be 
rewritten with the new bad block information. Blocks that you enter manually and that BAD 
decides are reliable are included in the bad block descriptor file. 

2.3 BAD and Indirect Command Files 

BAD can access an indirect command file that contains a series of BAD command lines in the 
following manner: 

BAD>«BADCMDS . CMD \M] 

In this example, BAD is invoked and accesses the file BADCMDS.CMD, which contains a 
sequence of BAD command lines. BAD executes the comands and returns with the BAD 
prompt. BAD allows nested command files — one command file can invoke another to a 
maximum depth of three. BAD can also be invoked within an indirect command file. Such a 
command file can contain command lines for more than one utility and is invoked by entering 
only the file specification preceded by the at sign ( @ ). For example: 

XBINDIRECT.CMD [RET] 

The format for entering file specifications is as follows: 

ddnn : [directory] filename . type ; version 

Refer to Chapter 1 for detailed descriptions of the parameters for file specifications. 
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The default values for indirect command file specifications are as follows: 
Element Default Value 



ddnn 


SYO 


directory 


The current directory 


filename 


No default 


type 


CMD 


version 


The latest version of the file 



For complete information on how to use indirect command files, see the RSX-llM-PLUS Indirect 
Command Processor Manual. 

2.4 Processing Bad Block Data 

This section contains information on how BAD tests the reliability of disks and DECtapes and 
formats bad block descriptor entries. It also describes how the MCR command INI uses bad 
block information. 

2.4. 1 Verifying Devices 

BAD verifies disks and DECtapes by writing a test pattern onto each of the blocks on the device, 
by reading the pattern into a buffer in memory, and by comparing the pattern written with the 
pattern read. When BAD processes a disk or DECtape, all existing data is destroyed. 

BAD writes the test pattern to several blocks in a single write operation. If an error occurs in 
vrating, reading, or comparing any of these blocks, BAD tests each of the blocks individually. 
The Pattern switch (/PAT=m:n) may be used to specify the doubleword test pattern. Its default 
values are 1655558 and 1333338, which are replicated 128io times per block. If BAD finds no 
bad blocks during individual testing, the error logging subsystem may stUl log errors due to 
long data transfers. 

2.4. 1 . 1 BAD and Non-Last-Track Devices 

As BAD locates bad blocks, it stores their addresses in a memory buffer. After locating all bad 
blocks on a device, BAD records the addresses of the bad blocks on the last good block of 
the device. Consecutive bad blocks are recorded as single entries. On non-last-track devices, 
BAD storage allows 126io entries of bad block addresses. If more than the maximum number 
of entries is recorded, BAD terminates with an error message. There must be at least one good 
block in the last 256io blocks of the volume for BAD to create this block information. 
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2.4.1.2 BAD and Last-Track Devices 

BAD records bad block information differently on last-track devices from non-last-track devices. 
Last-track devices include the RK06/07, RLOl/02, and the RM02/03/05/80 devices. The last 
track is divided into two areas, the Manufacturer's Detected Bad Sector File (MDBSF) and 
the Software-Detected Bad Sector File (SDBSF). The MDBSF is created when the manufacturer 
formats the pack. This operation also sets bits in any header that is marked bad in the MDBSF 
and sets the SDBSF to be empty. When you run BAD, entries are made in the SDBSF. BAD 
storage allows 126io entries of bad block addresses. The information contained in the two 
last-track files is combined to form the bad block file [0,O]BADBLK.SYS when you issue the 
MCR command INI. 

2.4.2 Format of Bod Block Descriptor Entries 

For non-last-track devices, BAD uses the last good block as a descriptor file for bad blocks. The 
address of a bad block, or the first address in a sequence of consecutive bad blocks, is stored as 
a doubleword entry in the bad block descriptor file. The first word of this doubleword contains 
two entries: the high-order byte contains the number of bad blocks minus 1 and the low-order 
byte contains bits 16 to 23 of the logical block number of a bad block or a range of bad blocks. 
The second word of the doubleword contains bits to 15 of that block number. 

For last-track devices, bad block descriptor entries are recorded as a doubleword in the SDBSF. 
The first word of the doubleword contains the address of the cylinder on which the bad block 
exists. The high-order and low-order bytes of the second word contain, respectively, the track 
and sector addresses of the bad block. 

2.4.3 INI Command and BAD 

Use BAD followed by the MCR command INI to produce a Files-11 volume. The INI command 
uses the bad block information to create the bad block file [0,0]BADBLK.SYS. The bad block 
file has allocated to it those blocks found to be bad and the last good block for non-last-track 
devices, thus ensuring that the file system does not allocate a known bad block to a file. 

For information on how to use the MCR command INI, see the RSX-llM-PLUS Command 
Language Manual. 

2.5 Using BAD 

Before BAD can validate a device, that device must be formatted by the manufacturer or by the 
Disk Volume Formatter (FMT) (see Chapter 9). 

The volume to be formatted must be mounted foreign and allocated by the user. 

You may execute BAD while other tasks are executing. 

Note that if the Allocate switch (/ALO:volumelabel) (see Section 2.2.1) is used with BAD, the 
volume must be mounted as a Files-11 device and the user must have a privileged account. 



2-8 Bad Block Locator Utility (BAD) 



Example 



ALL DM1 : \M] 

MOU DM1: /FOR (RET] 

FMT DM1 : [/switch] (Ml 

BAD DM1 : [/switch] \m] 

INI DM1 : [label] [/switch] [RET] 

DM0 DM1 : [RET] 

MOU DM1 : [label] [/switch] 



Illustrates a typical sequence of steps for introducing a disk to an RSX-llM-PLUS operating 
system. 

2.5. 1 Programming Considerations 

This section contains information you should know before you use BAD. 

2.5.1.1 Useof BlocIcO 

On bootable disks, block contains the bootstrap block. If block is bad, BAD prints a message 
warning the operator not to use the disk for a bootable system image. 

2.5. 1 .2 Device Controller Errors 

The error logging subsystem may log errors even though BAD is not reporting bad blocks. 
These errors may be encountered during long data transfers and may originate with the device 
controller. 

2.6 BAD Messages 

The following sections list the BAD messages, give a brief description of the condition that causes 
each message, and suggest a response to the condition. BAD messages are either informational 
or error messages. The messages are arranged alphabetically begiiuung with the text following 
the device symbol, ddnn. 

Messages are issued to your terminal in the following format: 

BAD — ddnn: message 

Error messages describe a condition that caused BAD to terminate the processing of a command. 
When this occurs, BAD returns to the highest level of command input. For example, if the 
command is entered in response to the Monitor Console Routine (MCR) prompt, BAD will issue 
the error message, exit, and prompt you wdth the MCR prompt, as follows: 

>BAD conmandline 
BAD — ddnn: message 
> 

If the command is entered in response to the BAD prompt, BAD will issue an error message 
and prompt you with the BAD prompt, as follows: 

BAD>coiiimandline 

BAD -- ddnn: message 

BAD> 
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BAD — ddnn: Failed to write Bad Blocl< Fiie 

Explanation: BAD could not write the bad block file. This condition usually results from a 
disk-write error. 

User Action: Reenter the command line. If the problem persists, the disk pack should be 
discarded. 

BAD — ddnn: Fatal tiardwore error 

Explanation: There is a hardware problem with the specified disk. 
User Action: Contact your DIGITAL Field Service representative. 

BAD — ddnn: Handler/Driver missing 

Explanation: The disk driver is not loaded. 

User Action: Load the disk driver and reenter the command line. 

BAD — ddnn: Home block not found 

Explanation: BAD was unable to read the home block while attempting to validate the 
volume label. This message only applies to the /ALOivolumelabel switch. 

User Action: The disk must be initialized by using the MCR command INI. 

BAD — ddnn: illegai device 

Explanation: The device to which bad block processing is directed does not support a Files-11 
structure. 

User Action: You must reformat your device before running BAD. 

BAD — invalid biocic number - n 

Explanation: You entered an invalid block number sequence. The value n is the invalid 
sequence. 

User Action: Specify another value and reenter the command line. This message applies to 
the /MAN, /ALO:volumelabel, or /UPD switches only. 

BAD — Invalid switcli 

Explanation: The specified switch is not a legal one for the BAD utility. 
User Action: Specify an appropriate switch and reenter the command line. 

BAD — ddnn: is on alignment cartridge 

Explanation: The factory-written label on the last track of a last-track device cartridge 
indicates an alignment cartridge (for use only by Field Service). 

User Action: Mount and process another cartridge. 
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BAD — ddnn: Manufacturer's Bod Sector File corrupt 

Explanation: The factory-written bad block data in the last track of a last-track device is in 
an inconsistent format. 

User Action: Specify the /OVR switch and reenter the command line. 

BAD — ddnn: Not in system 

Explanation: The requested device was not made part of the system during system generation, 
or the device does not exist on the host configuration. 

User Action: Ensure that you entered the command line correctly and that you specified the 
right device. 

BAD — ddnn: Not ready 

Explanation: The unit had not reached operating speed when BAD attempted to access it. 
User Action: Allow the unit to reach operating speed; then, reenter the command line. 

BAD — ddnn: Privilege vioiation 

Explanation: An operation was attempted for a device that was mounted or allocated to 
another user. 

User Action: Allocate another device, mount the device (if necessary), and reenter the 
command line. 

BAD — Syntax error 

Explanation: BAD detected a syntax error on the command line. 

User Action: Determine the correct syntax and reenter the command line. 

BAD — ddnn: Unrecoverable error n 

Explanation: An I/O error caused BAD to terminate. The value n is the error code number 
of the I/O error returned by the driver. 

User Action: See the RSX-llM-PLUS and Micro/RSX I/O Operations Reference Manual for 
an explanation of the error code number. If the same error persists, contact your DIGITAL 
Field Service representive. 

BAD — ddnn: Volume label incorrect 

Explanation: The volume label entered with the /ALO:volumelabel switch did not match 
the label on the disk. 

User Action: Use the correct volume label and reenter the command line. 

BAD — ddnn: Write locked 

Explanation: The unit is write-locked. 

User Action: Write-enable the unit and reenter the command line. 
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Chapter 3 

Backup and Restore Utility (BRU) 



The Backup and Restore Utility (BRU) allows you to back up and restore Files-11 volumes. You 
can use BRU to transfer files from a volume to a backup volume (or volumes) to ensure that a 
copy is available in case the original files are destroyed. If the original files are destroyed, or if 
for any other reason the copy needs to be retrieved, you can restore the backup files with BRU. 
In the process of copying, BRU also reorganizes and compresses files for efficient storage and 
access. 

You can use BRU stand alone as well as on line. BRUSYS is the standalone version. Refer to 
Section 3.5 for more information on standalone BRU. 

Backup and restore operations take place on disk and magnetic tape volumes as follows: 

• Disk to tape — for backup operations 

• Tape to disk — for restore operations 

• Disk to disk — for either backup or restore operations 

In addition to these basic data transfer functions, BRU provides command qualifiers that allow 
you to do the following: 

• Initialize disks 

• Perform selective backup and restore operations 

• Perform volume and data checking 

• Display information such as backup set names and file names 

Section 3.9 contains examples of various BRU operations. 

BRU can also be invoked through the DIGITAL Command Language (DCL) command BACKUP. 
For more information, see the RSX-UM-PLUS Command Language Manual. 
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3.1 On-Line BRU Disk and Tape Device Information 

BRU uses disk and tape volumes for its backup and restore operations. Input disks must be in 
Files-11 format. For tapes and multivolume backup disks, BRU has its own format. 

BRU backs up from mounted foreign and mounted disk volumes. 

BRU does not use the file system on input disks. However, when you are using a mounted 
volume for a backup operation, BRU checks the read access privileges of directories and files 
against the User Identification Code (UIC) under which BRU is running. To back up from a 
mounted disk volume that is in Files-11 format, you must specify the /MOUNTED qualifier. 
For disks mounted foreign, no qualifier is necessary. 

BRU also restores to volumes mounted foreign or moimted Files-11. Specify the /INITIALIZE 
qualifier to restore to a volume mounted foreign. This qualifier initializes the volume to Files-11 
format. To restore to a moimted Files-11 volume, specify the /NOINITIALIZE qualifier to 
indicate to BRU that the disk is mounted and already in Files-11 format. 

BRU backs up to and restores from tape volumes. The tapes must be mounted foreign. No 
qualifier is necessary. 

Table 3-1 summarizes the correct combinations of mount status and qualifiers. BRU returns an 
error message for any wrong combination of conditions. 

Table 3-1: Mounting and Initializing Volumes 



Volume 



Mount Status 



Mandatory 
Qualifier 



Input disk 
Output disk 



Input tape/ 
Output tape 



Mounted foreign 
Mounted Files-11 
Mounted foreign 
Mounted Files-11 
Mounted foreign 



None 

/MOUNTED 

/INITIALIZE 

/NOINITIALIZE 

None 



For more detailed information on Files-11, refer to the RSX-llM-PLUS and Micro/RSX I/O 
Operations Reference Manual. 

With BRU, you can also specify that a disk volume contain up to 65,500 files. The default is 
the value assigned to the input disk. See the descriptions of the /HEADERS and /MAXIMUM 
qualifiers in Section 3.3 for more information. 
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3.1.1 Backup Sets 

A backup set consists of all the data directed to a tape or disk volume (or volumes) during a 
single backup operation. Physically, more than one backup set may be contained on a tape or 
disk, or a backup set can extend over several tapes or disks. 

Files in the backup set cannot be accessed directly; therefore, the backup set must first be 
restored before the individual files in the backup set can be accessed. 

A backup set created on a tape volume or volumes is called a tape set. Tape sets are created 
by a conventional backup operation. 

A backup set created on a disk volume or volumes is called a disk set. Disk sets are created by 
an image backup operation. 

3.1.1.1 Conventional Bockup Operation 

A conventional backup to tape copies the files from the original disk to a backup set on a BRU 
format tape. The backup set can span multiple tapes and you can append additional backup 
sets to the first volume. You cannot access the files in the backup set directly. Therefore, you 
must restore the backup set to disk before you can access the individual files contained in it. 

A conventional backup to disk copies the files from the original disk to another Files-11 disk. 
You can access the files on the input disk or the output disk directly, eliminating the need to 
do a restore operation. 

If the output disk already has a Files-1 1 structure, you can add the files from the original disk. 
If the output disk does not have a Files-11 structure, you must use BRU with the /INITIALIZE 
qualifier to create a Files-11 structure on the output disk. 

3.1.1.2 Image Backup Operation 

An image backup to disk copies the original disk to a container file on another Files-11 disk 
(or disks). Image backups are used for multivolume backup operations. 

A disk container file has features similar to features of tapes created by a conventional backup 
to tape. A disk container file can span multiple disks, and you can add several backup sets to 
a container file. 

If you want to do a backup operation, you must specify the SAVE option with the /IMAGE 
qualifier. If you want to do a restore operation, you must specify the RESTORE option with 
the /IMAGE qualifier. In order to access the files in a backup set, you must restore the backup 
set to another disk. (See Section 3.3 for a description of conunand qualifiers.) 

If the output disk already has a Files-11 structure, you can add the container file to it. If the 
output disk does not have a Files-1 1 structure, BRU creates its own structure on the disk with 
the container file. 
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3.1.2 Full and Selective Backup Operations 

You can classify a backup operation by how much of the original tape or disk you are backing 
up. 

The following backup operations are available to you: 

• Full 

• Selective 

A full backup or a selective backup refers to the files you are backing up. 

A full backup transfers all the original files to a backup volume (or volumes). Thus, a full 
backup ensures that you have a complete copy of the original disk. 

A selective backup is a partial backup. If you do a selective backup, a subset of the original 
tape is backed up. You select and identify the files to be backed up by directory, date, or file 
specification. 

One type of selective backup is the incremental backup. An incremental backup is a backup 
of files by date only. Incremental backups and selective backups are helpful over a short time 
span when a full backup would take up too much time or too many system resources. 

3.1.3 Multivolume Tape and Disk Operations 

When you specify a magnetic tape drive as the output device or when you specify a disk for 
an image backup in a BRU operation, BRU transfers the data contents of the input disk to the 
tape or disk on the drive. This data transfer often involves more than one reel of tape or more 
than one disk and may use more than one tape or disk drive. 

You can specify more than one type of drive in a single BRU command. However, although 
you can specify up to eight drives per command, you can specify an individual tape or disk 
drive only once. 

If the number of volumes required exceeds the number available, BRU lets you replace tapes or 
disks on the specified drive in round-robin fashion. 

You can only use all 7-track or all 9-track tapes in a multivolume tape set. You cannot switch 
from one track type to the other within the set. 

You can only use the same disk types when backing up to multiple disks in image mode. You 
cannot mix disks. 
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3.1.4 Supported Devices 

Table 3-2 lists all the devices that On-Line BRU supports. The disks from DB to EM are all 
block-structured devices. 

Table 3-2: Devices Supported by On-Line BRU _^_^___ 



Mnemonic Type 



DB RH11/RP04/RP05/RP06 or RH70/RP04/RP05/RP06 disk pack 

DD TU58 cassette (DECtape II) 

DF RFll/RSll fixed-head disk 

DK RK11/RK05/RK05F cartridge pack 

DL RL11/RL01/RL02 cartridge disk 

DM RK611/RK06/RK07 cartridge disk 

DP RP11/RP02/RP03 disk pack 

DR RH70/RM03/RM05/RM80/RP07 or RH11/RM02 disk pack 

DS RH11/RS03/RS04 or RH70/RS03/RS04 fixed-head disk 

DT TC11/TU56 DECtape 

DU RA80/RA60/RA81/RA82/RC25/RD51/RD52/RD53/RD54/RX33/RX50 disk 

DX RXll/RXOl diskette 

DY RX211/RX02 diskette 

EM MLll electronic memory 

MF TM78/TU78 9-track magnetic tape (on VMS systems with VAX-11 RSX only) 

MM RH11/TM02-03/TE16/TU16/TU45/TU77 

RH70/TM02-03/TE16/TU16/TU45/TU77 9-track magnetic tape 



MS TS11/TSV05/TU80 9-track magnetic tape 

MT TMll/TElO/TUlO 7- or 9-track magnetic tape 

TS03 9-track magnetic tape 

MU TK50 cartridge tape drive 

TU81E 9-track magnetic tape 



3.2 BRU Command Line 

This section describes the rules for entering command lines for BRU. This section defines 
the command line format and describes prompts, command line parameters, and command 
qualifiers. BRU command lines have a maximum length of 256io characters except in one case 
that uses continuation lines (see Section 3.2.2). 

You can execute an indirect conunand file containing BRU commands from BRU. Tjrpe an at 
sign ( @ ) followed by the file specification for the indirect command file. 
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You can invoke BRU by any of the methods described in Chapter 1. The command line for 
BRU is shown next. 

Format 

/qualifier[...] indevice[,...][filespec[,...]] outdevice[,...] 

Parameters 

qualifier 

Specifies any of the command quahfiers described in Section 3.3. If two or more qualifiers 
are specified, they must be contiguous, that is, separated with a slash only. The qualifiers 
can appear in any order. 

When a qualifier has options, you must separate the qualifier from the option with a 
colon (:). 

You can use a shorter form of a qualifier as long as it is unique. All BRU qualifiers are 
unique to three characters. Table 3-3 lists the BRU qualifiers. 

indevlce 

Specifies the input device you want to transfer files from. In a backup operation, the input 
device contains the files you want to safeguard. In a restore operation, the input device 
contains the backup set you are restoring. 

Devices are specified in the following form: 

ddnn: 

Refer to Chapter 1 for a detaUed decription of this parameter. 

There is no default for the input device. It must be specified. 

For a restore operation, up to eight input devices may be specified, separated by commas. 
BRU restores the backup set beginning on the first device and continuing on the other 
devices in the order specified. If the number of volumes in the backup set you are restoring 
exceeds the number of input devices specified, BRU prompts you to place additional volumes 
on the specified drives, one at a time. 

fliespec 

Specifies the file specification used to select particular files or categories of files to back up 
or restore. A file specification takes the following form: 

[directory] filename .type ; version 

Refer to Chapter 1 for detailed descriptions of the parameters for file specifications. 

You may specify as many as 16 file specifications per command, separating the file 
specifications by a comma. The file specification always follows the input device. If 
more than one input device is specified, the file specification must follow the first input 
device. Note that file specifications may not be placed after the output device. 

When you enter a command without a file specification, all the files on the input volume 
are copied to the output volume. 
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Files can also be backed up or restored selectively by directory, file name, file type, or 
version number. If only the directory is specified, the remainder of the file specification 
will be treated as a wildcard; for example, [directory] is equivalent to [directory]*.*;*. If the 
version number is omitted, a wildcard is the default; for example, filename.type is equivalent 
to filename.type;*. Note, however, that BRU does not accept or -1 as version numbers. 

outdevice 

Specifies the output device you want to transfer the files to. In a backup operation, the 
output device contains the backup set you want to create. In a restore operation, the output 
device is the disk that receives the files you are restoring. 

There is no default for the output device. It must be specified. 

In a backup operation, up to eight output devices may be specified, separated by commas. 
BRU creates the backup set beginning on the first device and continviing on the other devices 
in the order specified. If the number of volumes required for the backup set exceeds the 
number of output devices specified, BRU prompts you to place additional volumes on the 
specified drives, one at a time. 

The format of outdevice is the same as for indevice (described previously). A file specification 
may not be placed after the output device. 

If you enter a RETURN key as the only character on the command line, the following prompts 
will appear: 

BRU> 

FROM: 

TO: 

INITIALIZE [Y/N] : 

The BRU> prompt requests that you enter the qualifiers needed to perform the desired 
operation. Refer to Table 3-3 for a summary of the BRU qualifiers. 

The FROM prompt requests that you enter the name (or names) of the devices on which the 
input volume (or volumes) reside. The names should be in the form specified in the previous 
description of the command line parameters. 

The TO prompt requests that you enter the name (or names) of the output devices. The names 
should be in tiie form specified in the previous description of the command line parameters. 

The INITIALIZE [Y/N] prompt requests that you enter Y (for Yes) if you want to initialize the 
output volume, or enter N (for No) if you do not want to initialize the output volume. 

There is no default answer. You must respond with either Y or N. 
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Table 3-3: Summary of BRU Command Qualifiers 



Command 
Qualifiers 


Options 


Default 


/APPEND 




None 


/BACKUP SET:name 




Volume name of the disk being 
backed up 


/BAD[:option] 


AUTOMATIC 

MANUAL 

OVERRIDE 


BAD:AUTOMATIC 


/BUFFERS:n 




Number of File Control Blocks 
(FCBs) from the input disk 


/COMPARE 




None 


/CREATED:option 


BEFORE:(dd-mmm-yy hh:mm:ss) 

BEFORE:dd-mmm-yy 

BEFORE:hh:mm:ss 

AFTER:(dd-mmm-yy hh:mm:ss) 

AFTER:dd-mmm-yy 

AFTER:hh:mm:ss 


Current Date 


/DENSITY:n 




Default density of drive 


/DIRECTORY 




None 


/DISPLAY 




None 


/ERRORS:n 




25 10 errors 


/EXCLUDE 




None 


/EXlbND:n 




Number of blocks from the input 
disk 


/HEADERS:n 




Number of headers allocated to 
the input volume 


/IDENTIFICATION 




None 


/IMAGE:option 


SAVE 
RESTORE 


None 


/INITIALIZE 




None 


/INVOLUME:name 




None 


/LENGTH:n 




The length of the output tape 


/MAXIMUM:n 




Maximum number of files al- 
lowed on the input volume 


/MOUNTED 




None 


/NEW_VERSION 




/NOSUPERSEDE 
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Table 3-3 (Cont.): Summary of BRU Command Qualifiers 



Command 






Qualifiers 


Options 


Default 


/NOINITIALIZE 




None 


/NOPRESERVE 




None 


/NOSUPERSEDE 




/NOSUPERSEDE 


/OUTVOLUME.name 




Input disk volume name 


/FOSITIONroption 


BEGINNING 
MIDDLE 
END 
BLOCK:n 


Index file position on the input 
disk 


/PROTECTION:option 


SYSTEM:value 
OWNER:value 
GROUP:value 
WORLD:value 


Protection of the input disk 


/REVISED:option 


BEFORE:(dd-mmm-yy hh:mm:ss) 

BEFORE:dd-mmm-yy 

BEFORE:hh:mm:ss 

AJHhR:(dd-mmm-yy hh:mm:ss) 

AFTER:dd-mmm-yy 

AFTER:hh:mm:ss 


Current date 


/REWIND 




None 


/SUPERSEDE 




/NOSUPERSEDE 


/TAPE TABEL:label 




None 


/Uf-U 




None 


/VERIFY 




None 


/WINDOWS:value 




Number of mapping pointers on 
the input disk 



3.2.1 Wildcards in Input Specifications 

The following wildcard ( • ) features are provided for input file directory specifications: 

[•] Specifies all directories. 

[*,*] Specifies all directories. 

[g,*] Specifies all member numbers for group g. 

[•,m] Specifies all group numbers for member m. 
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BRU also supports the wildcard in the file name, file type, and version number elements of 
the file specification. BRU follows the rules for use of wildcards (see the RSX-llM-PLUS MCR 
Operations Manual) except in the following two instances: 

• If the version number is omitted, it will be treated as a vrildcard. For example, NAME.EXT 
is the equivalent of NAME.EXT;*. 

• If only the directory is specified, the entire file specification vydll be treated as a wildcard. 
For example, [directory] is the equivalent of [directory]*.*;*. 

3.2.2 Continuation Lines 

BRU command lines have a maximum length of 256io characters. BRU allows you to continue 
a command line onto more than one line by using a hyphen ( - ) as the continuation character. 

On the RSX-llM-PLUS operating system, BRU supports continuation lines under all 
circumstances. However, when you use BRU from the Monitor Console Routine (MCR) 
command level, the total nimiber of characters for the initial command line and any subsequent 
continuation lines cannot exceed 80. 

Section 3.9 gives examples of continuation lines on the RSX-llM-PLUS operating system. 

3.3 BRU Qualifier Descriptions 

The following sections describe the BRU command qualifiers in detail. 

3.3.1 Append 

The Append qualifier (/APPEND) directs BRU to append a backup set from the input disk 
volume to the last backup set on the output tape, or on the output disk if you are using the 
/IMAGE qualifier. 

If the output tape is positioned at the beginning, the /APPEND qualifier causes BRU to skip to 
the logical end-of-tape before it vmtes the new backup set. BRU searches the output volume 
for the last logical end-of-file. 

If the output tape is already positioned at the logical end-of-tape, the /APPEND qualifier causes 
BRU to start writing where the device is currently positioned. 

If the output tape is not positioned at the beginning, or if it is not at the logical end-of-tape, 
you can use the /liEWIND qualifier with the /APPEND qualifier to rewind the tape and then 
space forward until the logical end-of-tape. 

If the tape is a continuation volume (that is, not the first tape or disk in a set) or if the last 
backup set does not end on the tape, BRU displays an error message. 

If the output device is a disk and you are using the /IMAGE qualifier, the /APPEND qualifier 
causes BRU to check the container file header for the logical end-of-file on the output disk. 
BRU then starts writing at the logical end-of-file. 

If the output disk is a continuation disk (that is, not the first disk in a set) or if the last backup 
set does not end on the disk, BRU displays an error message. 

You cannot use the /APPEND qualifier during a backup operation to a mounted disk. 
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Note 

BRU detects and automatically skips over a bootable system image (for example, BRUSYS) when 
appending to or restoring from a magnetic tape. This feature allows you to place a BRU backup 
set onto a magnetic tape that contains a bootable system image at its beginning and eliminates 
the need for a separate magnetic tape containing the bootable system image. 

When BRU is used to append to or restore from a magnetic tape which contains a bootable 
system image, there will be a small delay for rewinding the tape and for skipping over the 
bootable system image. 

When placing the first backup set on a magnetic tape that contains a bootable system image, 
you must specify /REW/ APPEND. You cannot leave the magnetic tape positioned at the end of 
the bootable system image and then specify the /APPEND qualifier. Also, the /TAPE_LABEL 
qualifier is ignored during a restore operation if there is a bootable system image at the beginning 
of the magnetic tape. 

3.3.2 Backup Set 

The Backup Set qualifier (/BACKUP_SET) names the backup set (refer to Section 3.1.1) to be 
placed on tape or disk. 

Format 

/BACKUP_SET:name 

Parameter 

name 

Specifies the name of the backup set. 

For a mounted input or output disk during an image backup or restore operation, you can 
specify the full backup set file name with the /BACKUP_SET qualifier. If you do not specify 
the file name, the default is [0,0]BACKUP.SYS. 

For tape and for an unmounted disk, the default name is the volume name of the disk 
being backed up. This name may be up to 12 characters long. 

When applied to an output volume, the backup set name assigns the name of the backup set 
being placed on the volume. BRU supports multiple backup sets on a single volume. 

When this qualifier is applied to an input tape volume, BRU searches the first tape for the 
specified backup set name. If you do not specify a backup set name with the input volume, 
BRU restores the first backup set it finds on the tape. You can restore several sequential backup 
sets from the same tape without rewinding the tape between BRU operations. BRU does not 
rewind the first device in a backup set unless you specify the /REWIND qualifier. 

When this qualifier is applied to an input disk volume, BRU searches the entire disk for each 
backup set you specify. Each backup set is then restored in the order of the backup set names 
you provided. 
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3.3.3 Bad 

The Bad Qualifier (/BAD) creates the bad block file BADBLK.SYS on the output disk. The /BAD 
qualifier is used with the /INITIALIZE qualifier during tape-to-disk or disk-to-disk operations. 

Format 

/BAD[:option] 

Parameter 

option 

Specifies one of the following three options: 

AUTOMATIC For last-track devices, the AUTOMATIC option causes BRU to use the 
manufacturer-written bad block information and the Software-Detected Bad 
Sector File (SDBSF) to create the bad block file BADBLK.SYS. For non- 
last-track devices, it uses the software bad block descriptor block to create 
BADBLK.SYS. AUTOMATIC is the default option. 

MANUAL The MANUAL option accepts the addresses of bad blocks you enter 

interactively at your terminal. It also specifies that BRU use either the 
manufacturer-written bad block information and the SDBSF (for last-track 
devices) or the bad block descriptor block (for non-last-track devices) to 
create the bad block file BADBLK.SYS. 

OVERRIDE The OVERRIDE option applies only to last-track devices, and it causes the 
last-track device to appear to be a non-last-track device. When OVERRIDE is 
specified, BRU uses the software bad block descriptor block to create the bad 
block file BADBLK.SYS and ignores the manufacturer-written information. 

For complete information on how to use the options for the /BAD qualifier, see Section 3.6. 

3.3.4 Buffers 

The Buffers qualifier (/BUFFERS) specifies the default number of directory File Control Blocks 
(FCBs) on each volume. The FCBs are stored in memory by the Ancillary Control Processor 
(ACP) when the volume is mounted. The more FCBs there are stored in memory, the faster 
files contained in heavily used directories are found. The default number of buffers is the same 
as for the input disk. 

Format 

/BUFFERS:n 

Parameter 

n 

Specifies the number of FCBs. 

The /BUFFERS qualifier is used with the /INITIALIZE qualifier during tape-to-disk or disk-to- 
disk operations. 
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3.3.5 Compare 

The /COMPARE qualifier (/COMPARE) compares the data on the output device with the data 
on the input device and reports any differences. No data transfer takes place during a compare 
operation. The command line specifying the compare operation must be identical to that entered 
when the data on the output disk or tape was created, with the exception of the /INITIALIZE, 
/NOINITIALIZE, and /APPEND qualifiers. 

When the compare operation detects differences, it displays a message at your terminal. The 
compare operation always displays the mnemonic of the device on which the difference was 
detected and the type of record in which the difference was encountered (a control record, a 
header record, or a data record). 

If the record type is a header record, the compare operation also displays the file ID for the file. 
If the record type is a data record, the compare operation also displays the file ID, the Logical 
Block Number (LBN) of the block in error, and the name of the file if it is available. 

3.3.6 Created 

The Created qualifier (/CREATED) backs up or restores files created before or after the specified 
date and/or time. 

Format 

/CREATED:option 

Parameter 

option 

Specifies one of the two options in three possible forms, as follows: 

BEFORE:(dd-mmm-yy hh:mm:ss) 

BEFORE:dd-mmm-yy 

BEFORE:hh:mm:ss 

AFrER:(dd-mmm-yy hh:mm:ss) 

AFTER:dd-mmm-yy 

AFTER:hh:mm:ss 

If you use the BEFORE option, BRU copies any files created before the specified date and/or 
time. 

If you use the AFTER option, BRU copies any files created on or after the specified date 
and/or at or after the specified time. 

If you specify both a date and a time, the date and time must be enclosed in parentheses. 
If you specify only a date or only a time, the parentheses are not necessary. If you specify 
only a time, BRU uses the current date as the default. If you specify only a date, the time 
defaults to 00:00. 
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3.3.7 Density 

The Density qualifier (/DENSITY) specifies the density, in bits per inch (bpi), at which BRU 
writes to tape. 

Format 

/DENSITY:n 

Parameter 

n 

Specifies the density. The following table shows the values you can specify: 



Drive 



Default 
Density 



Optional 
Density 



TUIO/TEIO 


800 


None 


TU16/TE16 


800 


1600 


TU45 


800 


1600 


TU77 


800 


1600 


TSll 


1600 


None 


TSV05 


1600 


None 


TU78 


6250 


1600 


TU80 


1600 


None 


TU81E 


6250 


1600 



If you specify the /DENSITY qualifier with the /APPEND qualifier, you must specify the density 
at which the existing tape data was written. For example, if the tape was first written at a 
density of 800 bpi, you must specify a density of 800 bpi. If you specify a density other than 
the original density, BRU displays a message and continues processing at the correct density. 

If you enter an incorrect density for a restore operation, BRU displays an error message and 
terminates the operation. 

3.3.8 Directory 

The Directory qualifier (/DIRECTORY) lists at your terminal the backup set names or files on 
the specified tape or disk volume. In a multivolume tape set, the directory is on the first tape 
of the set. In a multivolume disk set, the directory is on the first disk of the set. 
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3.3.8. 1 Displaying Bacicup Set Names 

When specified with no backup set name, the /DIRECTORY qualifier lists all the backup sets 
on the volume. 

Example 

BRU> /DIRECTORY MMO: 

VOLl BACKUPl LABEL! 2-Jan-87 
VOLl BACKUP2 LABELl 3-Jan-87 

BRU> /DIRECTORY DUO: 

VOLl BACKUPl LABELl 13-Jun-87 
V0L2 BACKUPl LABEL2 14-Jun-87 

3.3.8.2 Dispiaying Fiie Names 

To display the names of files in a backup set, enter the backup set name by using the /BACKUP- 
SET qualifier with the /DIRECTORY qualifier. 

If the backup set is not on the tape or disk, BRU halts execution and displays a message at your 
terminal. 

Example 

>RUN BRU 

BRU>/BACKUP_SET : 23MAY87A/DIRECT0RY MMl : 

VOLl. 23MAY87A HVIIHDOC 13-JUN-87 23:37:11 

[000,000] 

[303.013] 

27DECE.LST;1 

2JANA.LST;1 

18JANC.LST;1 

4JANA.LST:2 

25DECA.MAC:1 

9DECA.LST;2 

X.MAC: 1 

X.0BJ;1 

X.TSKil 

APNDXC.TXT; 1 

X.MAP;1 

[001,054] 

RSX11M.STB;4S 

[002,064] 

RSX11M.STB;36 

[003,054] 

RSX11M.STB;3 

[005,064] 

[306,006] 

APNDXB.MACil 

BRU - Completed on MMl: 

BRU> rCTRL/Z| 
> 

Displays the names of the files in the backup set. 
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3.3.9 Display 

The Display qualifier (/DISPLAY) prints, at your terminal, the file name and directory of each 
file as the header for that file is being transferred by BRU. 

3.3.10 Errors 

The Errors qualifier (/ERRORS) terminates a restore operation after the specified number of 
nonfatal tape-read errors is reached. 

Format 

/ERRORSm 

Parameter 

n 

Specifies the number of errors. The range of numbers is to 65535. The default number 
of errors before termination is 25 iq. 

3.3.11 Exclude 

The Exclude qualifier (/EXCLUDE) backs up or restores all of the files on the tape or disk except 
the files specified on the command line. 

3.3.12 Extend 

The Extend qualifier (/EXTEND) specifies the default number of blocks by which a file is 
extended when that file has exhausted its allocated space. 

Format 

/EXTEND:n 

Parameter 

n 

Specifies the number of blocks. This value is used by the ACP when the volume is mounted. 
The default is the number of blocks from the input disk. 

The /EXTEND qualifier is used with the /INITIALIZE qualifier during tape-to-disk or disk-to- 
disk operations. 

3.3.13 Headers 

The Headers qualifier (/HEADERS) specifies the number of file headers to allocate initially to 
the index file. 

Format 

/HEADERS:n 
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Parameter 

n 

Specifies the number of file headers. 

The five system files (INDEXF.SYS, BITMAP.SYS, BADBLK.SYS, CORIMG.SYS, and 
OOOOOO.DIR) are not included in n. The primary reason for preallocating file headers 
is to locate them near the storage bit map file. (The storage bit map file is generally located 
in the middle of the disk.) Proper placement of file headers can help reduce head motion 
during I/O operations. The default is the number of headers allocated to the input volume. 

The /HEADERS qualifier is used with the /INITIALIZE qualifier during tape-to-disk or disk-to- 
disk operations. 

If you want to copy files from a disk with a single-header index file (structure level 401) to a 
disk wdth a multiheader index file (structure level 402), specify a number of file headers with 
the /HEADERS qualifier and a number of files with the /MAXIMUM qualifier that are both 
large enough to make the output disk contain a multiheader index file. See the description of 
the MCR command INI in the RSX-UM-PLUS MCR Operations Manual and the DCL command 
INITIALIZE in the RSX-llM-PLUS Command Language Manual for a table of maximum and 
default values. 

3.3.14 Identification 

The Identification qualifier (/IDENTIFICATION) directs BRU to identify itself by displaying its 
version. This qualifier may be specified on a command fine alone or in combination with other 
qualifiers. 

3.3.15 image 

The Image qualifier (/IMAGE) specifies that you want to do a multiple disk-to-disk backup or 
restore operation. 

Format 

/IMAGEroption 

Parameter 

option 

Specifies one of the following two options: 

SAVE If you are doing a backup operation, you must specify the SAVE option on 

the command line. 

RESTORE If you want to do a restore operation, you must specify the RESTORE option 
on the command line. 

If you want to do a backup operation, you must use this qualifier when you create the backup 
file that represents the image copy of the input disk or disks. For example, this qualifier must 
be used when you copy a large disk to several small disks, or if you copy several small disks 
to a mounted large disk. 

If you want to do a restore operation, you must use this qualifier when restoring from a backup 
file that represents the image copy of the original disk. 
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3.3.16 Initialize 

The Initialize qualifier (/INITIALIZE) specifies that you want to initialize the output disk during 
a tape-to-disk or disk-to-disk operation. 

Initialization places a Files-11 structure on the disk, including the boot block; the home block; 
and such files as INDEXF.SYS, BADBLK.SYS, BITMAP.SYS, CORIMG.SYS, and OOOOOO.DIR. 

The volume must be mounted foreign. BRU returns a privilege violation if the conditions are 
not met satisfactorily (see Table 3-1). 

Along with the /INITIALIZE qualifier, you can specify the following qualifiers when you 
initialize a disk: 

/BAD 

/BUFFERS 

/EXTEND 

/HEADERS 

/MAXIMUM 

/NOPRESERVE 

/OUTVOLUME 

/POSITION 

/PROTECTION 

/WINDOWS 

If you do not specify any of these qualifiers, BRU defaults to the characteristics of the input 
volume except for the /BAD qualifier and the /NOPRESERVE qualifier. For the /BAD qualifier, 
the default is AUTOMATIC. For the /NOPRESERVE qualifier, there is no default. 

3.3.17 Involume 

The Involume qualifier (/INVOLUME) specifies the volume label of the input disk. 

Format 

/INVOLUME:name 

Parameter 

name 

Specifies the name of the volume label. This name can be up to 12io characters long. 

For disk-to-tape or disk-to-disk operations, the /INVOLUME qualifier directs BRU to look for 
the volume label of the input volume to verify that the disk has the correct label. This check 
ensures that you do not back up the wrong volume. 

For restore operations, the /INVOLUME qualifier directs BRU to check the volume label of the 
disk that is stored in the backup set on tape or in the image backup set file on the disk. 



3-18 Backup and Restore Utility (BRU) 



3.3.18 Length 

The Length qualifier (/LENGTH) spedfies the length of the output tape. 

Format 

/LENGTH:n 

Parameter 

n 

Specifies the length of the output tape in decimal feet. If the length specified exceeds the 
length of the tape, the entire length of the output tape is used. In cases where you know 
the end of a tape must not be used, you can specify a shorter length to ensure that you do 
not write on that part of the tape. 

Note 

This qualifier should not be used with cartridge tape devices such as the TK25 and TK50. 

3.3.19 Maximum 

The Maximum qualifier (/MAXIMUM) specifies the maximum number of files that can be placed 
on a volume as determined by the number of file headers in the volume's index file. (BRU 
supports up to 65,500 files on a volume.) 

Format 

/MAXIMUM:n 

Parameter 

n 

Specifies the number of files. The default is the maximum number of files on the input 
disk. The value includes the five system files. 

The /MAXIMUM qualifier and the /HEADERS qualifier are particularly useful when you are 
initializing an output disk that is different in size from the input disk. 

If you want to copy files from a disk with a single-header index file (structure level 401) to 
a disk with a multiheader index file (structure level 402), specify a number of files with the 
/MAXIMUM qualifier and a number of file headers with the /HEADERS qualifier that are both 
large enough to make the output disk contain a multiheader index file. See the description of 
the MCR command INI in the RSX-llM-PLUS MCR Operations Manual and the DCL conunand 
INITIALIZE in the RSX-llM-PLUS Command Language Manual for a table of maximum and 
default values. 
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3.3.20 Mounted 

The Mounted qualifier (/MOUNTED) allows you to back up files from a disk that is mounted 
as a Files-11 volume (by means of the MCR or DCL command MOUNT). 

If you use the /MOUNTED qualifier when the input device is a tape, BRU issues a syntax error. 

BRU does not use the file system to read files from the input disk. Instead, it issues logical 
queue I/Os (such as lO.RLB). To issue these QIOs to a mounted FiIes-11 disk, BRU must be 
built as a privileged task (PR:0). (BRU does not have to be privileged for operations on volumes 
mounted foreign.) However, when you are restoring to a mounted disk (and you have specified 
the /NOINITIALIZE qualifier), BRU uses the file system to access the output disk. Therefore, a 
restore operation to a mounted disk is slower than a restore to an unmounted disk. 

BRU must also be privileged to back up a disk that is being accessed by other users. The 
/MOUNTED qualifier must be specified in the command line. 

When backing up files from a mounted volume, disk activity (changes to or deletion of files) 
while BRU is running provides the following results: 

• If the file is being changed while BRU is backing up the disk, BRU copies only the data 
that comprise the file at the time of the ti-ansfer. Any changes made to the file after the 
transfer will not appear in the file on the output volume. 

• If the file is deleted while BRU is backing up the disk, the data that comprise the file may 
be corrupted. 

If the file ID from the deleted file is reused in a directory that BRU has not yet backed 
up, BRU will back up the new file (with the previously allocated file ID) when that file 
is encountered. When restored, this new file (with the reused file ID) will appear as a 
synonym for the old file with the same file ID. 

• If the disk is changed (files are deleted or changed) after BRU generates the directory, the 
directory on the first tape of the tape set or the directory in the backup set file on the disk 
will not be accurate. Because BRU generates the directory for the backup set as its first 
processing step, changes to the disk after the directory is generated will not be reflected in 
the directory. 

• If the file or data are being changed during a bransfer operation, BRU will not be able to 
verify the accuracy of the operation. Do not attempt a verify operation in this case. 

Note that this restriction also includes the file being used by the error logger. The error 
logging file changes when any hardware errors occur, which can cause the verify operation 
to fail. To ensure that the verify operation succeeds, switch the error logging file to a 
different disk or exclude it with the /EXCLUDE qualifier. 

3.3.21 New Version 

The New Version qualifier (/NEW_VERSION) resolves file specification conflicts that occur 
during restore operations and during backups to a mounted disk. 

When a file already exists on the output disk volume, the /NEW_ VERSION qualifier creates a 
new version of the file. You cannot use the /VERIFY qualifier when you specify the /NEW- 
VERSION qualifier. If these qualifiers are specified together, BRU will issue a "Conflicting 
qualifiers" error message. 
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3.3.22 Noinitialize 

The Noinitialize qualifier (/NOINITIALIZE) specifies that you do not want to initialize the 
output disk because it is already in Files-11 format. The output disk must be mounted as a 
Files-11 volume. 

You cannot enter any of the initialization qualifiers when you specify the /NOINITIALIZE 
qualifier. If you enter any of these qualifiers, BRU issues an error message. 

3.3.23 Nopreserve 

The Nopreserve qualifier (/NOPRESERVE) specifies that you do not want to preserve file IDs 
(file IDs are generally preserved). If you specify the /NOPRESERVE qualifier, BRU suppresses 
the message that file IDs are not being preserved. Note that in restoring to a mounted disk, not 
preserving file IDs is BRU's default action. 

The /NOPRESERVE qualifier is used only wiih the /INITIALIZE qualifier. 

When file IDs are not preserved, BRU assigns new file IDs and increments them sequentially. 

3.3.24 Nosupersede 

The Nosupersede qualifier (/NOSUPERSEDE) specifies that when file specifications on the 
mounted output disk are identical to those on the input volimie, the file on the input volume 
is not transferred. That is, the file on the output disk is not superseded by the file on the input 
volume. 

When an output file and an input file have identical file specifications but different version 
numbers, the /NOSUPERSEDE qualifier causes the input file to be copied, but it does not 
delete the output file. The /NOSUPERSEDE qualifier is the default. 

3.3.25 Outvolume 

The Outvolume qualifier (/OUTVOLUME) specifies the volume label of the output disk. 

Format 

/OUTVOLUME:name 

Parameter 

name 

Specifies the name of the volume. This label can be up to 12io characters long. 

For disk-to-tape backup operations, the name of the input disk volume stored on the output 
tape volume is changed to the name specified with the /OUTVOLUME qualifier. 

For tape-to-disk restore operations or for disk-to-disk transfers, the name of the output disk 
volume is changed to the name specified with the /OUTVOLUME qualifier. 

When you omit the /OUTVOLUME qualifier, BRU provides tiie following defaults: 

• In backup operations, the input disk volume name is used as the volume name stored on 
the output tape volume. 
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• In restore operations, the volume name stored on the input tape volume is used as the 
name of the output disk volume. 

• In disk-to-disk transfers, the volume name of the input volume is used as the volume name 
of the output volume. 

3.3.26 Position 

The Position qualifier (/POSITION) specifies the location of the index file on the output disk 
volume being initialized, usually to minimize access time. 

Format 

/POSITIONroption 

Parameter 

option 

Specifies one of the four possible location options, as follows: 

BEGINNING 
MIDDLE 
END 
BLOCK:n 

The BEGINNING, MIDDLE, and END options specify the beginning, middle, and end 
of a volume. The BLOCK:n option specifies a block, n, where the index file is to be 
placed. Generally, the BEGINNING or END option is used oiJy when a disk contains large 
contiguous files. MIDDLE is recommended to minimize access time. 

When you use the BLOCK:n option, the number is decimal by default (the period (.) is 
optional). To specify an octal number, place a number sign (#) in front of the number. If 
there are any conflicts, BRU issues a warning message. 

When you do not use the /POSITION qualifier, BRU places the index file in the same location 
as that on the input volume. 

3.3.27 Protection 

The Protection qualifier (/PROTECTION) specifies the default protection status for all files 
created on the output volume being initialized. This protection value does not apply to files 
being transferred by BRU, but rather to subsequent files created on the output volume by the 
Ancillary Control Processor (ACP) when the volume is mounted. If you do not specify any 
values, they default to the protection values of the input disk. 

Format 

/PROTECTION:option 
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Parameter 

option 

Specifies one of the four possible options, as follows: 

SYSTEM:value 
OWNER:value 
GROUP:value 
WORLD:value 

The protection value can be R (read), W (write), E (extend), or D (delete), or any combination 
of the four. 

See the RSX-llM-PLUS MCR Operations Manual for an explanation of file protection. 

3.3.28 Revised 

The Revised qualifier (/REVISED) backs up or restores files revised or created on, before, or 
after the specified date and time. 

Format 

/REVISED:option 

Parameter 

option 

Specifies one of the two options in three possible forms, as follows: 

BEFORE:(dd-mmm-yy hh:mm:ss) 

BEFORE:dd-mmm-yy 

BEFORE:hh:mm:ss 

AFTER:(dd-mmm-yy hh:mm:ss) 

AFTER:dd-mmm-yy 

AFTER:hh:mm:ss 

If you use the BEFORE option, BRU copies any files revised or created at or before the 
specified date and/or time. 

If you use the AFTER option, BRU copies any files revised or created on or after the specified 
date and/or at or after the specified time. 

As with the /CREATED qualifier, if you specify both a date and time, the date and time must be 
enclosed in parentheses. If you specify only a date or time, the parentheses are not necessary. 
If you specify only a time, BRU uses the current date as a default. If you specify only a date, 
the time defaults to 00:00. 
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3.3.29 Rewind 

The Rewind qualifier (/REWIND) rewinds the first magnetic tape of a tape set before executing 
a backup or restore operation. 

When specified with an input tape, BRU rewinds the first tape of the tape set before searching 
for a backup set. 

When specified with the /APPEND qualifier, BRU rewinds the output tape and then searches 
for the logical end-of-tape before executing the backup operation. 

3.3.30 Supersede 

The Supersede qualifier (/SUPERSEDE) specifies that when file specifications on the mounted 
output volume are identical to file specifications on the input volume, the file on the output 
volume is deleted and replaced with the file from the input volume. 

For a multiple disk-to-disk backup or restore operation (using the /IMAGE qualifier), if you 
create a backup set file on a mounted volume, and a file with the same name exists, the 
/SUPERSEDE qualifier replaces this file. 

The /NOSUPERSEDE qualifier is the default. 

3.3.31 Tape Label 

The Tape Label qualifier (/TAPE —LABEL) specifies the volume identifier to be placed on a tape 
during a backup operation or to be compared with the label on the tape for append and restore 
operations. 

Format 

/TAPE_LABEL:label 

Parameter 

label 

Specifies the 6-character identifier. This label allows you to check that you are using the 
correct tape. 

3.3.32 UFD 

The UFD qualifier (/UFD) directs BRU to create directories (if they do not already exist) on a 
mounted output volume, and it then directs BRU to copy into them the files from the same 
directory on the input volume. If you do not specify the /UFD qualifier, BRU does not copy 
the files. 

The /UFD qualifier is used only with the /NOINITIALIZE qualifier. 
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3.3.33 Verify 

The Verify qualifier (/VERIFY) verifies that the output volume was written correctly by comparing 
the input volume to the output volume and reporting any differences. 

During a backup operation, each tape or disk is verified before starting the next volume in 
the backup set. During a restore operation, however, the entire backup set is restored before 
beginning the verify operation. 

3.3.34 Windows 

The Windows qualifier (/WINDOWS) specifies the default number of mapping pointers to be 
allocated for file windows when initializing an output disk. 

Format 

/WINDOWS:n 

Parameter 

n 

Specifies the number of pointers. This value is used by the ACP when the volume is 
mounted. A file window consists of a number of pointers and is stored in memory when 
the file is opened. The default number of mapping pointers is the same as for the input 
disk. 

Choosing a large number of mapping pointers may speed up file access. However, a large 
file window also uses up system dynamic memory (pool). If pool space is more critical than 
file access time, choose a smaller number of pointers. 

Refer to the RSX-UM-PLUS and Micro/RSX I/O Operations Reference Manual for more 
information. 

3.4 Command Qualifier Functions 

When you initialize a disk by using the BRU qualifier /INITIALIZE, use the foUovdng qualifiers 
to specify various characteristics for the output disk: 

/BAD 

/BUFFERS 

/EXTEND 

/HEADERS 

/MAXIMUM 

/NOPRESERVE 

/OUTVOLUME 

/POSITION 

/PROTECTION 

/WINDOWS 
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The /MOUNTED qualifier allows you to copy files from a mounted disk. 

The following command qualifiers allow you to copy files to a mounted disk with various 
results. Note that the following qualifiers are not available in standalone BRU (see Section 3.5): 

/NEW_VERS10N 

/NOINITIALIZE 

/NOSUPERSEDE 

/SUPERSEDE 

/UFD 
The following command qualifiers allow you to backup or restore data: 

/CREATED 

/EXCLUDE 

/REVISED 
These qualifiers backup and restore data according to the following: 

File specification 

Date and time of creation 

Date and time of revision 
The following qualifiers allow you to control backup and restore tape processing: 

/APPEND 

/BACKUP-SET 

/DENSITY 

/ERRORS 

/LENGTH 

/REWIND 

/TAPE_LABEL 

The following command qualifiers allow you to detect differences between data on the input 
volume and data on the output volume: 

/COMPARE 

/INVOLUME 

/VERIFY 
The following command qualifiers display information about the files being transferred: 

/DIRECTORY 

/DISPLAY 
The /IDENTIFICATION qualifier directs BRU to identify itself by displaying its version number. 
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The /IMAGE qualifier is for both disk image backups and restore operations. 

3.5 Standalone BRU 

You can also run BRU stand alone. On the RSX-llM-PLUS operating system, the standalone 
system is called BRUSYS. The difference between the BRU task contained in this standalone 
system and the On-line BRU described in the preceding sections is that standalone BRU does 
not support a restore operation to a mounted volume. Therefore, BRU will always initialize the 
output disk volume. There is no /INITIALIZE qualifier and the BRU task does not ask if you 
want to initialize the output volume. 

Other qualifiers that cannot be used in the standalone BRU systems are the /NEW_VERSION, 
/NOINITIALIZE, /NOSUPERSEDE, /SUPERSEDE, and /UFD qualifiers. 

On an RSX-llM-PLUS operating system, BRUSYS contains fovu' other tasks besides the BRU 
task. These other tasks are BAD, CNF, DSC, and FMT. The Bad Block Locator Utility (BAD) 
is described in Chapter 2, the Standalone Configuration and Disk Sizing Program (CNF) is 
described in this chapter, the Disk Save and Compress Utility Program (DSC) is described in 
Chapter 6, and the Disk Volume Formatter Utility (FMT) is described in Chapter 9. You invoke 
BAD, BRU, DSC, and FMT with the MCR command RUN. CNF is invoked automatically when 
you boot the system. (You can use CNF again by invoking it with the RUN command.) 

If you need to use BAD or FMT, you must run them before runiung BRU. When you are finished 
with these other tasks, issue the RUN BRU command to begin using BRU. 

BRU and BAD should not be used simultaneously because they use common buffer space. 
Running both tasks at the same time yields unpredictable results. 

After you boot the standalone BRU system, the CNF task runs automatically. It lists the 
switches available for your use and then prompts you for the devices you will be using. It is 
recommended that you first specify /DEV to find out the status of the devices on your system, 
as follows: 

Enter first device: /DEV 



Device 



CSR 



Vector CSR Status 



DB 


176700 


254 


Present 


DK 


177404 


220 


Present 


DL 


174400 


160 


Not Present 


DM 


177440 


210 


Present 


DP 


176714 


300 


Present 


DR 


176300 


150 


Present 


DU 


172150 


154 


Not Present 


MF FOR=0 


175400 


260 


Not Present 


MM FORK) 


172440 


330 


Present 
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Device CSR Vector CSR Status 



MS 


172522 


224 


Not Present 


MT 


160000 


320 


Not Present 


MU 


174500 


260 


Present 



Enter first device: 

You can also use CNF and its switches to set the control and status register (CSR) and vector 
addresses of devices present on your system or to change the default formatter number (FOR=n) 
for some of the magnetic tape devices, as follows: 

Enter first device: 0M2 : /CSR=177450/VEC=274 

Enter second device: DL: 

The CNF switches are listed in Table 3-4. 



Table 3-4: CNF Switches 



Switch Format Function 



CSR /CSR=n Changes the default CSR number for the device. 

Device /DEV Lists the default CSR and vector addresses for all of the devices. It is 

recommended that you use this switch first to find out what devices 
are present on your system. 

Formatter /FOR=n Changes the default formatter number for some of the magnetic tape 

devices. The qualifier is valid for only the MF- and MM-tjqpe devices. 
The initial default for n is 0. 

Vector /VEC=n Changes the default vector number for the device. 

3.5. 1 Locating and Booting Standalone BRU 

The BRUSYS system on the distribution kit requires 124K words of memory to run the five tasks 
(BAD, BRU, CNF, DSC, and FMT). The BRUSYS system image and symbol table are located in 
directory [6,54] on the distribution disk. 

On the RSX-llM-PLUS operating system, you can bootstrap the standalone BRU system in 
one of two ways, as follows: 

• Software boot standalone BRU by using the privileged MCR command BOOT as follows: 

>INS $B00 

>B0O [6, 84] BRUSYS 

• Hardware boot standalone BRU following the hardware bootstrap procedure for your 
processor. 
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To create a hardware-bootable, standalone BRU tape from the distribution disk, use the 
Virtual Monitor Console Routine (VMR) to save the system image to tape as follows: 

>MOU MT:/FOR 

>SET /UIC=[6.54] 

>ASN SY:=LB: 

>RUM VMRM42 

ENTER FILENAME: BRUSYS 

VMR>SAVEMT : BRUSYS 

VMR> ICTRl/ZI 

This tape contains a hardware-bootable image of the standalone BRU system. (See the 
RSX-llM-PLUS and Micro/RSX System Management Guide for information on VMR.) 

3.6 On-Une BRU Bad Block Processing 

After you have formatted a disk with the Disk Volume Formatter Utility (FMT; see Chapter 9) 
and marked any bad blocks on it with the Bad Block Locator Utility (BAD; see Chapter 2), you 
can initialize it with BRU. 

BRU uses the bad block information from running BAD on the disk to create the file 
BADBLK.SYS. This file has allocated to it all of the bad blocks on the disk so that other 
files will not try to use them. 

The /BAD qualifier has three options: AUTOMATIC (which is the default option), MANUAL, 
and OVERRIDE. The following sections describe how to use these options. 

3.6.1 Using the AUTOMATIC Option 

The AUTOMATIC option specifies that BRU use the existing bad block information on the 
disk to create the file BADBLK.SYS. For last-ti-ack devices, BRU uses the manufacturer-written 
bad block information and the Software-Detected Bad Sector File (SDBSF). For non-last-track 
devices, BRU uses the bad block descriptor block. 

3.6.2 Using the MANUAL Option 

The MANUAL option accepts the addresses of bad blocks you enter interactively at your 
terminal. It also specifies that BRU use either the manufacturer-written bad block information 
and the SDBSF (for last-track devices) or the bad block (for non-last-track devices) descriptor 
block to create BADBLK.SYS. If there is no software-written bad block information, a message 
will be displayed informing you that BAD has not processed the disk. 

When you specify /BAD:MANUAL, BRU issues a prompt at your terminal. To enter bad blocks, 
respond to the prompt with the starting logical block nimiber (LBN), followed by a coimt of 
how many consecutive blocks are bad. 

Format 

LBN[:count[.]] 

BRU interprets both the LBN and the count as decimal numbers. You can specify the LBN in 
octal, but you must specify the count in decimal. To specify an octal value for the LBN, precede 
it with a number sign (#). If you do not specify count, it defaults to 1. 
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If you enter a bad block that is already in the bad block file, BRU generates an "Duplicate 
blocks found" error message. 

To get a list of the LBNs you have typed so far, type a slash (/ ) or press the RETURN key. 

When you have finished entering bad blocks, type two slashes (//). BRU will then allocate 
the bad blocks that you have entered to BADBLK.SYS and continue processing. 

3.6.3 Using the OVERRIDE Option 

The OVERRIDE option applies only to last-track devices. It makes the disk appear to be a 
non-last-track device. 

When you use OVERRIDE with BRU, ensure that the disk you are processing has been processed 
previously by the BAD utility with the /OVR switch specified. Using the BAD switch /OVR 
makes last-track devices look like non-last-track devices by using the last good block before the 
last track as the bad block descriptor block. The OVERRIDE processing includes that last track 
as bad data when it creates the bad block descriptor block. 

OVERRIDE processing for BRU assimies that the bad block descriptor block written by BAD 
exists on the disk being processed. 

3.7 Using BRU to Copy Disks Containing System Images 

When you copy a bootable system disk to a disk of the same controller type, BRU automatically 
produces a bootable output disk for you. 

If, however, you are copying an unsaved (virgin) system or copying a saved system to a smaller 
disk or to a disk of a different controller type, you can use the procedures described in the 
following sections to ensure that BRU produces a bootable output disk. 

3.7.1 Copying an Unsaved (Virgin) System 

In an unsaved system, installed tasks are pointed to by the physical LBN of the task image 
on the disk. When you copy an unsaved system with BRU, BRU assigns new LBNs for the 
task images on the output disk. Therefore, if you want to be able to software boot the copied 
system, you must first use Virtual Monitor Console Routine (VMR) to remove and reinstall any 
tasks. (VMR is described in the RSX-llM-PLUS and Micro/RSX System Management Guide.) 

3.7.2 Copying a Saved System 

In a saved system, installed tasks are pointed to by the file ID of the task image on the 
disk. To copy a saved system to a smaller disk or to a disk of a different controller type, see 
Sections 3.7.2.1 and 3.7.2.2. 

3.7.2.1 Copying to a Smaller Disk 

If you want to copy a disk with a saved system to a smaller disk, the most common method is 
to first use the /MAXIMUM and /HEADERS qualifiers (described in Section 3.3) to decrease the 
size of the index file. BRU is then unable to preserve the file IDs of the files, so you must use 
VMR to remove and reinstall any tasks in the copied system image (the image on the output 
disk). 
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3.7.2.2 Copying to a Different Controiier Type 

If you have used BRU to copy a hardware-bootable disk to a disk of a different controller type 
and you want the output disk to also be hardware bootable, you must use the MCR command 
BOOT to boot the saved system on the output disk. Then you use the MCR command SAV 
/WB to write the correct boot block on the output disk. 

You can copy a DB-, DM-, DU-, EM- or DR-type disk to any other of these controller types 
without having to SAVE the system again because the boot block for these devices is common 
on the RSX-llM-PLUS operating system. Use the following command to write the correct boot 
block on the output disk: 

>SAV /WB \M] 

3.8 BRU File Treatmeiit 

The following sections describe how BRU treats file dates, file headers, file synonyms, and lost 
files. 

3.8. 1 Creation and Revision Dates of Files 

BRU always preserves the creation and revision dates of files that it transfers. However, since 
BRU creates directories during a restore operation to a disk being initialized, and also when the 
/UFD qualifier is specified, the creation date of the directory is the date on which BRU created 
it. 

3.8.2 File Headers 

BRU preserves all characteristics of a file, if possible. There are three exceptions, as follows: 

• If there is insufficient room on the output volume to restore the file contiguously, it is 
restored noncontiguously. 

• The file name is updated in the file's header to match the directory entry. 

• The physical end-of-file (EOF) in the user attribute area is updated to reflect the file's size 
correctly. 

3.8.3 File Synonyms 

File synonyms are files that have different names but share the same file ID and data. They 
can be created with the Peripheral Interchange Program (PIP) but also occur when a file ID 
from a deleted file is reused in a directory that BRU has not yet copied. If you restore files with 
synonyms to an unmounted volume and you preserve file IDs, the file synonyms are restored 
as synonyms. However, if you do not preserve file IDs or you restore to a mounted volume, 
file synonyms are restored as separate files. 

3.8.4 Lost Files 

A file that is not contained in any directory is known as a lost file. BRU does not find lost files. 
To find lost files, use the File Structure Verification Utility (VFY) with the Lost switch (/LO) 
before using BRU to back up the disk. (The VFY utility is described in Chapter 14.) 
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3.9 BRU Examples 

This section gives examples of various BRU operations and command lines. Note that the 
qualifiers used in the command lines have been truncated to three characters. All of the BRU 
qualifiers are unique to three characters. 

Examples 1 to 6 and Examples 11 and 12 also show informational messages that BRU returns 
during some operations. The other examples do not include these messages. 

The following list is a summary of the operations and command lines shown in the examples: 

1. Disk-to-tape backup (with verification) and tape-to-disk restore operations 

2. Disk-to-disk backup operations 

3. Disk-to-disk backup operation including changing the maximum number of files and initial 
header allocation for the output disk 

4. Disk-to-disk multivolume backup operation 

5. Disk-to-disk multivolume restore operation 

6. Disk-to-disk multivolume backup (with appending) and disk-to-disk restore operation 

7. Disk-to-tape incremental backup operation (by date) with tape verification 

8. Disk-to-tape selective backup operation (by file specification) 

9. Mounted disk-to-tape backup and tape-to-mounted disk restore operations 

10. Disk-to-tape backup (with appending) and tape-to-mounted disk restore operations 

11. Exclusion of certain files during a backup operation 

12. Manually entering bad blocks and displaying them 

13. Continuation command lines 

14. Continuation command lines (from MCR) 

Examples 

1. This example shows how to use BRU to back up an entire disk volume onto two 1600-bpi 
magnetic tapes and then how to restore the disk. For the backup operation, BRU verifies the 
output volumes as part of the operation. (Verifying volumes is specified with the /VERIFY 
qualifier.) If files do not verify, BRU returns an error message. 

Use the following command lines to back up DM2 onto the magnetic tapes on MMO and 
MMl: 

>MOU DM2: /FOR \M\ 

>MOU MMO -./FOR |MI 

>MOU MMl: /FOR [M] 

>BRU /DEN:1600/VER DM2: MMO: .MMl: [RET] 

BRU - Starting tape 1 on MMO: 

BRU - End of tape 1 on MMO: 

BRU - Starting verify pass tape 1 on MMO: 

BRU - End of tape 1 on MMO: 
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BRU - Starting tape 2 on MMl: 

BRU - End of tape 2 on MMl: 

BRU - Starting verify pass tape 2 on MMl: 

BRU - End of tape 2 on MMl: 

BRU - Completed 

> 

Use the following command lines to restore the entire disk and rewind the first input tape. 
(The /INI qualifier specifies that DM2 will be initialized before the restore operation begins.) 

>ma vmjfm gS 
>um mmjTm S 
>MO!lJ mt:/¥m. IMI 

>BWJ /BEW/DEII::1600/I1!II M'. ,mi'. IDM2' HJfl 
BRU - Starting tape 1 on MMO: 

BRU — *WARNING* — This disk will not contain a hardware bootable system 

BRU - End of tape 1 on MMO: 

BRU - Starting tape 2 on MMl: 

BRU - End of tape 2 on MMl: 

BRU - Completed 



2. This example shows how to do a disk-to-disk backup operation for an entire disk. The 
characteristics of the output disk default to those of the input disk. This operation (and 
every other BRU operation) can be done in two ways. 

The following command lines cause BRU to iiutialize the output disk (DM1) and then back 
up all of the files on the input disk (DM0) onto it: 



>MW ISM: /mm 'gll 
>mi mi:/fm K 

>mS}/m DM: BMl: 
BRU - Completed 

> 

or 



>BBU gr| 

BRU>IM1 

FROM: m'.ljWn 

TO: mi:. Ml 

INITIALIZE OUTPUT DISK [Y/N] : T 

BRU - Completed 

BRU>IS^SJ 
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3. This example shows another disk-to-disk backup operation. This time, the maximum 
number of files and initial file header allocation for the output disk are changed. This 
information is contained in the index file, which can be placed at different locations on the 
disk. 

This command initializes the output disk (DM1) and tells BRU that the maximum number of 
files allowed on the disk will be 10,OOOio ^^^ the initial file header allocation will be SOOOio 
headers. The index file, which contains this information, will be placed at the beginning of 
the disk. When the output disk has been initialized, all of the files on the input disk (DM) 
will be copied onto it. 

>tlOV DM: /FOR [RET] 

>MOU DM1: /FOR \M\ 

BRO>/INI/MAX : 10000/HEA : 5000/POS : BEG DM : DM1: [RET] 

BRU - Completed 



4. This example shows a multiple disk-to-disk backup operation. You must use the SAVE 
option with the /IMAGE qualifier when doing a multiple disk-to-disk backup operation. 



>MOU DL: label [RETJ 

>MOU DY:/FOR [RETI 

>BRU/INI/IMA:SAV/VER/MOU DL: DY: [M] 

BRU - Mount disk 1 on DYO: . Press "RETURN" when done 

BRU - Starting disk 1 on DYO: 

BRU - End of disk 1 on DYO: 

BRU - Starting verify pass disk 1 on DYO: 

BRU - End of disk 1 on DYO: 

BRU - Mount disk 2 on DYO: . Press "RETURN" when done 

BRU - Starting disk 2 on DYO: 

BRU - End of disk 2 on DYO: 

BRU - Starting verify pass disk 2 on DYO: 

BRU - End of disk 2 on DYO: 

BRU - Mount disk 3 on DYO:. Press "RETURN" when done 

BRU - Starting disk 3 on DYO: 

BRU - End of disk 3 on DYO: 

BRU - Starting verify pass disk 3 on DYO: 

BRU - End of disk 3 on DYO: 

BRU - Completed 

> 
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5. This example shows a image disk-to-disk restore operation. You must specify the RESTORE 
option on the command line with the /IMAGE qualifier. 

>MOU DY:/FOR [M] 

>MOU DL:/FOR [RET] 

>BRU/INI/IMA:RES/VER DY: PL: [RET] 

BRU - Mount disk 1 on DYO: . Press "RETURN" when done 

BRU - Starting disk 1 on DYO: 

BRU - This disk will not contain a hardware bootable system 

BRU - End of disk 1 on DYO: 

BRU - Mount disk 2 on DYO : . Press "RETURN" when done 

BRU - Starting disk 2 on DYO: 

BRU - End of disk 2 on DYO: 

BRU - Mount disk 3 on DYO: . Press "RETURN" when done 

BRU - Starting disk 3 on DYO: 

BRU - End of disk 3 on DYO: 

BRU - Mount disk 1 on DYO: . Press "RETURN" when done 

BRU - Starting verify pass disk 1 on DYO: 

BRU - End of disk 1 on DYO: 

BRU - Mount disk 2 on DYO: . Press "RETURN" when done 

BRU - Starting verify pass disk 2 on DYO: 

BRU - End if disk 2 on DYO: 

BRU - Mount disk 3 on DYO: . Press "RETURN" when done 

BRU - Starting verify pass disk 3 on DYO: 

BRU - End of disk 3 on DYO: 

BRU - Completed 



6. This example shows how to append backup sets on a multivolume disk, and it also shows 
how to restore the multivolume disk set. If your multivolume backup disk contains a backup 
set that does not occupy the entire disk, you can append backup sets on the same disk by 
using the /APPE^fD qualifier. 

>MOU DB:/FOR [RETI 

>MOU DK:/FOR \M] 

>MOU DK1:/FQR [RET] 

BRU>/APP/ IMA : SAVE/BACKUP : SECOND/ INI [RET] 

FROM: DB: \M1 

TO: DK:.DK1: [RET] 

BRU - Mount disk 1 on DKO:. Press "RETURN" when done. 

BRU - Starting disk 1 on DKO: 

BRU - End of disk 1 on DKO: 
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BRU - Mount disk 2 on DKl:. Press "RETURN" when done. 

BRU - Starting disk 2 on DKl: 

BRU - End of disk 2 on DKl: 

BRU - Completed 

> 

To restore the appended backup set from the multivolume disk set, you have to spedfy the 
following: 

>BRU/IMA : RES/BACKUPSET : SECOND/INI DK : . DKl : DBO : \M1 
BRU - Mount disk 1 on DKO : . Press "RETURN" when done . 

BRU - Starting disk 1 on DKO: 

BRU - End of disk 1 on DKO: 

BRU - Mount disk 2 on DKO:. Press "RETURN" when done. 

BRU - Starting disk 2 on DKl: 

BRU - End of disk 2 on DKl: 

BRU - Completed 

> 



7. This example shows how to do an incremental backup operation by date and with tape 
verification. 

The following command lines back up all files on the disk that were revised after 5:00 P.M. 
on 14 February 1987. After all the files have been copied onto the tape, BRU verifies the 
tape. If files on the tape do not verify, BRU returns an error message. 



>MOU DM: /FOR HHl 
>MOU MT:/FOR \M} 

>BRU/REV:AFT:(14-FEB-87 17:00) /VER 
FROM: DM: [RET] 
TO: MT: [RET] 



8. This example shows how to do a selective backup operation by file specification. 

In this case, BRU backups up all the files in directory [7,10] and all the fUes with type MAC 
and CMD in directory [301,304] on the input disk to a magnetic tape. 

>MaU DB:/F0R \Mi 

>MaU MM: /FOR [Ml 

>BRU DB : [7. 10] , [301 ,304] * .MAC, * .CMD [Ml 

TO: MM:fiETl 



9. This example shows how to back up files from a mounted disk and then two ways to restore 
files to a mounted disk. 
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The following command line informs BRU that the input disk is mounted as a Files- 11 
device: 

BRU>/MOU DL: [304,303] . [7,326] MM: [M] 

The following command line restores the files in directory [304,303] on the magnetic tape 
to the mounted disk volume without first initializing it. In this case, any file on the tape 
that is identical to a file already on the disk is not superseded (the input file is not copied). 
Not superseding files is the default operation for BRU. 

>BRU/NOINIT MM: [304,303] DB: [RET] 

The following command line restores the files in directory [7,326] on the magnetic tape to 
the mounted disk volume without first initializing it. The /NEW—VERSION qualifier tells 
BRU to create a new version of any duplicate files. 

>BRU/NOINIT/NEW MM: [7.326] DB: \M] 



10. This example shows how to append files from a disk to a tape with a backup set already 
on it and then how to restore the set back to a mounted disk. 

The command line appends the files in directory [7,326] on the input disk to a magnetic 
tape. The name of the backup set being vmtten on the tape is "TODAY." After the backup 
operation is completed, BRU verifies the tape, as follows: 

>BRU/APP/VER/BAC: TODAY [RET] 
FROM: DB: [7,326] \M} 
TO: MM: [rIT] 

The following command line rewinds the magnetic tape containing the backup set "TODAY." 
All of the files in TODAY are then copied back onto a mounted output disk. If a file already 
exists on the disk, BRU defaults to the /NOSUPERSEDE qualifier to resolve the conflict. 

> BRU/REW/BAC : TODAY/NO I MM : DB : [M] 



11. The following example backs up all of the files on the input disk, except for those in 
directory [1,6], onto the magnetic tape: 

>BRU/MOU/EXC DM:[1,6] MMl: [RET] 
BRU - Starting tape 1 on MMl: 

BRU - End of tape 1 on MMl: 

BRU - Completed 



12. This example shows how to enter bad blocks manually and how to display them. 
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The command line first initializes the output disk and then requests you to enter the 
locations of any bad blocks before copying the files from the magnetic tape. The first 
slash (/) displays the bad blocks in the bad sector file on the last track of the disk. The 
second slash displays those blocks and the ones that have been entered manually. Two 
slashes ends the entry of bad blocks and BRU continues the restore operation. 

In this example, two locations of bad blocks for the disk were entered: there are two bad 
blocks starting at LBN 10500 and one block at LBN 12000. You can enter the LBN in either 
decimal (the default) or octal (precede the number with #), but the number of bad blocks, 
if specified, must be in decimal. The default number of bad blocks is 1. 

>BRU/REW/INI/BAD:MAN MMl : DM: [M] 
BRU - Starti ng t ape 1 on MMl: 
BRU>LBN(S)=/[BII] 

053768:022 
BRU>LBN(S)=10500:2 
BRU>LBN(S) =12000 
BRU>LBN(S)=/[M] 

053768:022 

010500:002 

012000:001 
BRU>LBN(S)=//[lll 

BRU -- *WARNING* — This disk will not contain a hardware bootable system 

BRU - End of tape 1 on MMl: 

BRU - Completed 



13. This example shows BRU continuation command lines (see Section 3.2.2 for more 
information). 

The RSX-llM-PLUS operating system supports continuation lines when you invoke BRU 
and then responds to the BRU> prompt. The command line can be 256io characters long. 

>BRU [ret] 
BRU>/REWIND- [RET] 
BRU>/INVOLUME: BACKUP- [RETI 
BRU>/BACKUP_ SET:25MAY87- [REH 
BRU>/TAPE_ LABEL :BRU123 Ml 
FROM: DM0: [Mj 
TO: MMO: \M\ 



14. The RSX-llM-PLUS operating system also supports continuation lines when you use BRU 
fi-om the MCR command level. In this case, the command line can only be 80 characters 
long (including the initial line). 

>BRU/REWIND- [RETI 
->/INV0LUME: BACKUP- [RETI 
->BACKUP_SET:25MAY87- \M\ 
->/TAPE_LABEL:BRU123 DM0: MMO: M] 
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3.10 BRU Messages 

This section lists BRU messages, describes the meaning of each message, and suggests actions 
to correct the errors. Error messages from the BRU utility are preceded by the mnemonic BRU. 

BRU has three kinds of messages: informational, warning, and fatal error. 

• hyformational messages do not require a response. An informational message provides 
information on the current state of your backup operation. 

• Warning messages are marked 'WARNING*. They inform you of conditions that require 
your consideration. Depending on the message and the operation, you decide what further 
action is called for, and the operation continues. 

• Fatal error messages are marked *FATAL«. They inform you of conditions that caused BRU 
to terminate execution of your command. The operation does not complete. 

The subsections that follow describe each type of message. The messages are listed in 
alphabetical order. 

3.10.1 Informational Messages 

BRU issues the following informational messages: 

BRU — BRU version xx.xx 

Explanation: This message identifies the version of the Backup and Restore Utility (BRU) 
being used. 

User Action: No user action is required. 

BRU — Completed 

Explanation: The backup operation is complete. 

User Action: Enter another BRU command line or exit by pressing CTRL/Z. 

BRU — End of disk n on ddnn 

Explanation: BRU finished transferring data or verifying the disk n on device ddnn. 
User Action: No user action is required. 

BRU — End of tape n on ddnn 

Explanation: BRU finished transferring data or verifying the tape n on device ddnn. 
User Action: No user action is required. 

BRU — Mount another disk 

Explanation: BRU is requesting that a new disk be mounted after encountering a fatal 
disk-write error. 

User Action: Mount a new disk on the drive. 
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BRU — Mount another tape 

Explanation: BRU is requesting that a new tape be mounted after encountering a fatal tape 
write error. 

User Action: Mount a new tape on the drive. 

BRU — Mount disk n on ddnn:. Press "RETURN" wtien done 

Explanation: BRU is requesting a disk for a backup or restore operation. 
User Action: Mount the disk n on the drive ddnn. 

BRU — Mount tape n on ddnn: 

Explanation: BRU is requesting a tape for a backup or restore operation. This message prints 
every 2 minutes until the tape is loaded. 

User Action: Mount the tape n on the drive ddnn. 

BRU — Please answer yes or no 

Explanation: BRU requires a YES or NO response. 
User Action: Enter YES or NO at your terminal. 

BRU — Starting disl< n on ddnn: 

Explanation: The disk n is being copied to (or from) the drive ddnn. 
User Action: No user action is required. 

BRU — Starting tape n on ddnn: 

Explanation: The tape n is being copied to (or from) the drive ddnn. 
User Action: No user action is required. 

BRU — Starting verify pass 

Explanation: The verify pass of a disk-to-disk operation is beginning. 
User Action: No user action is required. 

BRU — Starting verify pass tape n on ddnn: 

Explanation: The tape n is being verified during a backup or restore operation. 
User Action: No user action is required. 

3.10.2 Warning Messages 

BRU issues the following warning messages: 
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BRU — WARNING — Allocation failure [dlrectory]filename.type;verslon 

Explanation: During a copy to a mounted volume, there was not enough free space to copy 
the specified file. 

User Action: Delete unnecessary files to create free space on the volume. Then, reenter the 
command line. 

BRU — WARNING — Appending at detault bpi on ddnn: 

or 

BRU — WARNING — Appending at 1600 bpi on ddnn: 

Explanation: Either of these messages indicate that you specified the wrong tape density 
with the BRU qualifier /APPEND. BRU performs an append operation only at the density 
at which the tape was previously written. The default bpi in the first message is either 800 
or 6250, depending on the type of tape drive. 

User Action: No user action is required. BRU continues at the density at which the tape 
was previously written. 

BRU — WARNING — Bad block data error 

Explanation: You entered an incorrect bad block location, count, or sjmtax. 

User Action: Enter the correct bad block information by using the BRU qualifier 
/BAD:MANUAL. 

BRU — 'WARNING* — Block exceeds volume size 

Explanation: You specified a bad block that is larger than the size of the output disk. 
User Action: Enter the correct block. 

BRU — WARNING — Boot block Is bad 

Explanation: The boot block is marked as bad on the output disk, so the disk is not hardware 
bootable. 

User Action: If you need a hardware-bootable disk, wait vmtil the operation completes. 
Then, repeat the procedure with a disk that has a usable boot block (logical block number 
(LBN) 0). 

BRU — WARNING — Boot block Is corrupt 

Explanation: The input disk does not contain a valid boot block, so the output disk will not 
be hardware bootable. 

User Action: If you need hardware-bootable output, use an input disk with a valid boot 
block (LBN 0). 
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BRU — WARNING — Boot block read error 

Explanation: An error occurred while BRU was reading the boot block. Although the input 
disk may contain a valid boot block, BRU was unable to read it. The output disk will not 
be hardware bootable. 

User Action: If you need a hardware-bootable disk, wait until the operation completes. 
Then, repeat the procedure. 

BRU — 'WARNING* — Boot block verify error on ddnn: 

Explanation: During a backup operation, the boot block on the output device did not match 
the boot block on the input device. 

User Action: If you need a hardware-bootable disk, wait until the operation completes. 
Then, repeat the procedure. 

BRU — WARNING — Canriot restore contiguously [dlrectory]fllename.type;version 

Explanation: The output device does not contain enough contiguous blocks to restore the 
indicated file contiguously. The file will be restored noncontiguously. 

User Action: Use the Peripheral Interchange Program (PIP) (see Chapter 12) to make the 
file contiguous again. Use the PIP switches /DE and /TR to reclaim disk space by deletion 
or truncation. 

BRU — -WARNING" — Close or write attributes error [directory ]fllename.type;verslon 
lO Error code number 

Explanation: During a copy to a mounted volume, BRU encountered an error while 
attempting to close the specified file. 

User Action: Determine the cause of the error from the I/O code (see the 
I^X-UM-PLUS MCR Operations Manual or the RSX-llM-PLUS Command Language Manual). 
If it is correctable, delete the portion of the file that BRU has copied. Then, reenter the 
command line. 

BRU — WARNING — Data ID record verify error 

Explanation: An error occurred while BRU was verifying an 80-byte, data-ID record. (A 
data-ID record is a control record used by BRU.) 

User Action: No user action is required. BRU continues the operation. 

BRU — WARNING — Data record verify error [directory]fllename.type;verslon 
File ID number LBN number 

Explanation: There is a difference in a data block on the input and output devices. The file 
ID of the file with the error and the LBN of the block follow the message. 

If a directory is printed with a file name, it is the owner directory from the file's header, 
not the directory in which the file is contained. 

User Action: Repeat the backup operation. If it fails again, repeat the operation with a 
different disk or tape. 
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BRU — WARNING — Data was lost due to lO errors 
[directory ]fllename.type;verslon 

Explanation: A read error resulted in missing data. The files may contain invalid data, and 
some of the files may not be restored. 

User Action: Repeat the backup operation. 

BRU — WARNING — Directory verify error 

Explanation: A directory record on the input device did not match a directory record on the 
output device. 

This error can occur when files are created, deleted, or renamed during the backup operation; 
BRU is unable to verify the data on the output device. It can also indicate a hardware error. 

User Action: Be sure the contents of the input disk do not change during the data transfer or 
verify operations. Before repeating the operation, be sure there is no activity on the disk. If 
you are backing up or restoring the system disk, be sure there is no activity on the system 
(such as Resource Accounting and error logging). Then, reenter the command line. 

BRU — 'WARNING- — Disk out of sequence. Please mount correct disk. 

Explanation: You mounted the wrong volume on the disk drive during a restore operation 
from a multidisk backup set. 

User Action: Mount the correct disk on the drive. 

BRU — WARNING — Disk read error 

Explanation: An unrecoverable read error occurred on the output disk, possibly caused by 
an undetected bad block, or an error occurred while BRU was sizing the input or output 
disk. 

User Action: Use the BAD utility to locate all bad blocks on the output disk. Then use BRU 
with the /BAD:AUTOMATIC qualifier to use the existing bad block information on the disk 
to create the file BADBLK.SYS. 

BRU— WARNING — Duplicate blocks found 

Explanation: You entered a bad block that is already listed in the bad block file. 
User Action: No user action is required. 

BRU — WARNING — EOT marker error 

Explanation: During a backup operation, an error occurred while BRU was writing or 
verifying the end-of-tape (EOT) label on the output tape. 

After a restore operation, an error occurred while BRU was positioning the tape at the end 
of a backup set for a subsequent operation. 

User Action: Your response depends on the type of error that has occurred. 

• On a write error, BRU rewinds the current tape and places it off line. BRU then asks 
you to mount a new tape. After you mount the new tape, BRU rewrites the data. 

• On a verify error, BRU continues the operation. 

Backup and Restore Utility (BRU) 3-43 



• On a positioning error, BRU finishes the operation. If you want to perform another 
BRU operation on the tape, use the /REWIND qualifier to position the tape to the 
beginning-of-tape (BOT). 

BRU — WARNING* — Error accessing file 
lO error code number 
File ID number 

Explanation: During a copy to a mounted volume, an error occurred while BRU was writing 
data into a file, or BRU tried to do a compare read on a file that was already opened. BRU 
continues with the next file. 

User Action: For a definition of the error code number, see the I/O error codes in the 
RSX-UM-PLUS MCR Operations Manual or the RSX-llM-PLUS Command Language Manual. 

After BRU finishes, delete the file. Then, reenter the command line and specify the file on 
which the error occurred. 

BRU — 'WARNING — Error accessing UFD Skipping [directory] 
lO Eror code number 

Explanation: During a copy to a mounted volume, an error occurred when BRU attempted 
to access a directory. 

User Action: For a definition of the error code number, see the I/O error codes in the 
RSX-llM-PLUS MCR Operations Manual or the RSX-llM-PLUS Command Language Manual 
Determine the cause of the error from the I/O error code. If the error is correctable, try the 
copy operation again. 

BRU — WARNING — Error reading data bioclts 
lO Error code number 
File ID number LBN number 
RECOVERED 

Explanation: An I/O error occurred while BRU was reading a data block from the input 
disk. The file identification (ID) of the file that contains the block and the logical block 
number (LBN) of the block are displayed, as well as the I/O error code. 

If RECOVERED is printed after the message, BRU recovered the block by reading the disk 
again. 

BRU continues the operation. 

User Action: For a definition of the error code number, see the I/O error codes in the 
RSX-llM-PLUS MCR Operations Manual or the RSX-llM-PLUS Command Language Manual 

BRU — WARNING — Error reading UFD [directory] 

Explanation: An I/O error occurred while BRU was reading a block from the specified 
directory. Any files contained in this block of the directory are not backed up. 

User Action: After the BRU operation completes, reenter the command line. Specify the 
directory indicated in the error message. 
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BRU — WARNING — Error reading UFD header [directory] 

Explanation: An error occurred while BRU was reading the header of the specified directory. 
Files in this directory are not backed up. 

User Action: Reenter the command line and specify the directory indicated in the error 
message. If the error still occurs, use the /LO switch with the File Structure Verification 
Utility (VFY) to find the lost fUes (refer to Chapter 14). 

BRU — WARNING — Extending index file 

Explanation: The initial number of file headers is too small. If the number of blocks on the 
output disk is greater than or equal to 5120io, BRU allocates 256io additional headers. If 
the number of blocks on the output disk is less than 5120io, BRU allocates I610 additional 
headers. 

User Action: No user action is required. BRU continues the operation with the extended file 
index. 

BRU — -WARNING* — File tieader read error [directory]fllename.type;version 
10 error code number 

Explanation: An I/O error occurred while BRU was reading a file header, so the 
corresponding file was skipped. BRU continues with the next file. 

User Action: For a definition of the error code number, see the I/O error codes in the 
RSX-UM-PLUS MCR Operations Manual or the RSX-llM-PLUS Command Language Manual. 

BRU — 'WARNING' — File tieader tile verify error [dlrectory]fllename.type;version 

Explanation: A file header is not the same on the input and output devices. 

This error can occur when files are created, deleted, or renamed during the backup operation; 
BRU is unable to verify the data on the output device. It can also indicate a hardware error. 

User Action: Be sure the contents of the input disk do not change during the data transfer or 
verify operations. Before repeating the operation, be sure there is no activity on the disk. If 
you are backing up or restoring the system disk, be sure there is no activity on the system 
(such as Resource Accounting and error logging). Then, reenter the command line. 

BRU — WARNING — File ID area verify error 

Explanation: The BRU-generated file ID area of a data record is not the same on the input 
and output devices. 

User Action: Refer to the previous message, "File header file verify error." 
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BRU — "WARNING — File ID sequence number error [directory ]fllename.type;version 
Explanation: The two possible sources of this error are as follows: 

1. The sequence number in the file ID of a file does not match the sequence number of 
the file's entry in the directory. 

2. The sequence number of a directory does not match the sequence number of the 
directory's entry in the Master File Directory (MFD). 

Therefore, the file or directory is not valid and is not copied. 

User Action: Repeat the backup operation. 

BRU — WARNING — File IDs will not be presen/ed 

Explanation: File IDs cannot be preserved because the index file bit map on the output 
device is too small. The value you specified with the /MAXIMUM qualifier is too small. 

User Action: No user action is required. BRU continues the operation without preserving 
file IDs. If you want the disk to be hardware bootable, perform the backup operation again, 
and specify a larger value with the /MAXIMUM qualifier. 

BRU — WARNING — File marlced for delete [directory ]fllename.type;version 

Explanation: The marked-for-deletion bit (SC.MDL) of the system-controlled characteristics 
in the file header is set, indicating that the file is partially deleted. So, BRU does not copy 
the file. 

User Action: No user action is required. BRU continues the operation with the next file. 

BRU — WARNING — File not found [dlrectory]fllename.type:verslon 

Explanation: During a backup operation, BRU cannot find a header in the index file 
(INDEXF.SYS) for a file or directory. BRU does not copy the file. 

During the verify or compare pass of a restore operation, BRU cannot find the file on the 
output device. 

User Action: No user action is required. BRU continues the operation with the next file. 

BRU — WARNING — File not superseded [dlrectory]filename.type:version 

Explanation: You attempted to restore a file to a mounted volume by using the 
/NOSUPERSEDE qualifier (the default). The specified file was not restored because it 
already existed on the output disk. 

User Action: If you want the file to be restored, reenter the command line. Specify the file 
and either the /SUPERSEDE or the /NEW_VERSION qualifier. 
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BRU — WARNING — Header ID record verify error 

Explanation: The header-ID record generated by BRU on the output device is incorrect. 

This error can occur when files are created, deleted, or renamed during the backup operation; 
BRU is unable to verify the data on the output device. It can also indicate a hardware error. 

User Action: Be sure the contents of the input disk do not change during the data transfer or 
verify operations. Before repeating the operation, be sure there is no activity on the disk. If 
you are backing up or restoring the system disk, be sure there is no activity on the system 
(such as Resource Accounting and error logging). Then, reenter the command line. 

BRU — WARNING* — Header read error [directory ]fllename.type;verslon 
lO error code number 

Explanation: During a backup operation, an I/O error occurred while BRU was reading a 
file header in the index file. 

During a restore operation, this error is fatal; the operation terminates. 

User Action: For a definition of the I/O error code number, see the RSX-UM-PIUS MCR 
Operations Manual or the RSX-llM-PLUS Command Language Manual. 

BRU — WARNING — Home block verify error 

Explanation: The home block on the output device is different from the home block on the 
input device. 

User Action: BRU continues, but you should repeat the operation. 

BRU — 'WARNING — Input volume structure level differs from output volume 

Explanation: You initialized the output volume with a value for the /MAXIMUM qualifier 
that is greater than 25,593. As a result, the index file (INDEXF.SYS) on the output volume 
has more than one file header. 

User Action: To make the volume structure the same on the input and output devices, 
initialize the output volume with a value for the /MAXIMUM qualifier that is less 
than 25,593. 

BRU — WARNING — Internal error 

Explanation: BRU has detected an error within itself. 

User Action: Reenter the command line. If the problem recurs, there is a problem with your 
software. 

BRU — WARNING — Invalid date or time [directory]fllename.type;version 

Explanation: BRU encountered an invalid date or time in a file header during an incremental 
backup. 

User Action: No user action is required. BRU continues the operation and the file is copied. 
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BRU — WARNING — Invalid disk format 

Explanation: If you were performing an /IMAGE :RESTORE operation, you mounted a disk 
that is not a multivolume backup disk. If you were performing an /IMAGE:SAVE operation, 
you attempted to append to a disk that is not a multivolume backup disk. The disk may 
be corrupted. 

User Action: Mount the correct disk and reenter the BRU command line. 

BRU — WARNING — MFD read error 

Explanation: An I/O error occurred while BRU was reading a block of the Master File 
Directory (MFD). BRU cannot copy the directories or files in that block of the MFD. 

User Action: Reenter the command line. If the header still cannot be read, the files on the 
disk are "lost." Use the /LO switch with the File Verification Utility (VFY) to recover the 
lost files (refer to Chapter 14). 

BRU — WARNING — No bad blocl< data found 

Explanation: You did not use the BAD utility to produce a file of the output disk's bad 
blocks. BRU continues the operation. 

User Action: For more information on bad block processing by BRU, see Section 3.6. 

BRU — WARNING — No flies found 

Explanation: During a backup or restore operation, BRU did not find any files to transfer. 
You may have entered the wrong file or directory specification. 

User Action: If you are sure you entered the correct file and directory specifications, no 
further action is necessary. If not, use the correct file specification and reenter the command 
line. 

BRU — WARNING — Nonfatal qualifier conflicts being Ignored 

Explanation: You entered a qualifier that conflicts with the rest of the command line. You 
used the /REWIND, /DENSITY, or /LENGTH qualifier during a disk-to-disk copy operation; 
or you used the /NEW_VERSION, /SUPERSEDE, or /NOSUPERSEDE qualifier during a 
disk to tape backup operation. 

User Action: No user action is required. BRU ignores all the conflicting qualifiers for the 
operation. 

BRU — WARNING — No such UFD exists. Skipping [directory] 

Explanation: During a copy to a mounted volume, BRU encountered one or more files in 
the specified directory on the input volume. However, there is no corresponding directory 
on the output volume. 

User Action: Specify the /UFD qualifier to create the directory and reenter the command 
line. 
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BRU — 'WARNING* — Open error [directory]fllename.type;version 
lO error code number 
File l/D number 

Explanation: During a copy operation to a mounted volume, an error occurred whUe BRU 
was attempting to open the specified file. 

User Action: For a definition of the error code number, see the I/O error codes in the 
RSX-llM-PLUS MCR Operations Manual or the RSX-llM-PLUS Command Language Manual. 
If the error is correctable, delete any portion of the file already copied by BRU. Then, reenter 
the command line. 

BRU — 'WARNING' — Privilege violation [dlrectory]fllename.type;version 

Explanation: During a backup operation, you attempted to copy a file that you did not have 
read access to. 

User Action: No user action is required. BRU does not copy the file. 

BRU — 'WARNING — Record not expected size 

Explanation: The record read on the output device during a verify or compare operation was 
not the expected size. 

User Action: No user action is required. 

BRU — 'WARNING' — Rewind error on ddnn 

Explanation: An I/O error occurred during a tape rewind. This error is fatal if it occurs on 
the first tape of a tape set or during a rewind for a verify operation. The error is not fatal 
if BRU is rewinding a tape it is finished with. 

User Action: If the error is fatal, reenter the command line. If the error is not fatal, no 
action is required. 

BRU — WARNING — Tope label error on ddnn 
lO Error code number 

Explanation: An I/O error occurred while BRU was reading or writing a tape label. A read 
error is not fatal as long as BRU can continue reading the tape. If a write error has occurred, 
BRU will display the message "BRU — Mount another tape." 

User Action: Specify a different tape and reenter the command line. 

BRU — WARNING — Tape label verify error 

Explanation: BRU detected an error in the tape label of the input or output tape volume 
during a verify operation. 

This error can occur when files are created, deleted, or renamed during the backup operation; 
BRU is imable to verify the data on the output device. It can also indicate a hardware error. 

User Action: Be sure the contents of the input disk do not change during the data faransfer or 
verify operations. Before repeating the operation, be sure there is no activity on the disk. If 
you are backing up or restoring the system disk, be sure there is no activity on the system 
(such as Resource Accounting and error logging). Then, reenter the command line. 
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BRU — 'WARNING — Tape out of sequence. Please mount ttie correct tape. 

Explanation: You mounted the wrong tape volume on the tape drive during a restore 
operation from a tape backup set. 

User Action: Mount the correct tape on the drive. 

BRU — WARNING — Tape positioning error. Backspace failed. 

Explanation: During a backup operation, the tape was not positioned properly for a future 
append operation. 

User Action: Rewind the tape by using /REWIND before attempting the append operation. 

BRU — WARNING— Tape read error 

Explanation: A nonrecoverable I/O error occurred while BRU was reading a tape. BRU 
ignores the error. 

User Action: No user action is required. 

BRU — WARNING — Tape write error 
lO Error code number 

Explanation: An I/O error occurred while BRU was writing to tape. BRU rewinds the tape 
and then requests that another tape be mounted. 

User Action: If the error is related to the tape drive, terminate the BRU operation and begin 
again from another tape drive. 

BRU — WARNING — This disk will not contain a liardware bootable system 

Explanation: The output disk will not be hardware bootable. This can be caused by one of 
the following: 

• The input disk is not bootable. 

• The input disk is not the same size or type as the output disk. 

• The system image (RSXllM.SYS) was not copied. 

This message is not issued when BRU is restoring to a mounted volume. 

User Action: If you want the output disk to be hardware bootable, use a bootable input disk 
and an output disk that is the same size as the input disk. Also, be sure the system image 
is included in the operation. 

BRU — WARNING* — UFD record verify error 

Explanation: A directory record is not the same on the input and output devices. 

This error can occur when files are created, deleted, or renamed during the backup operation; 
BRU is unable to verify the data on the output device. It can also indicate a hardware error. 

User Action: Be sure the contents of the input disk do not change during the data transfer or 
verify operations. Before repeating the operation, be sure there is no activity on the disk. If 
you are backing up or restoring the system disk, be sure there is no activity on the system 
(such as Resource Accounting and error logging). Then, reenter the command line. 
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BRU — WARNING VBN nof in die 

Explanation: A file ID was encountered that is larger than the maximum file ID in the index 
file. The file is ignored. This error message occurs if a directory entry was corrupted on the 
input disk. 

User Action: No user action is required. 

BRU — WARNING — Volume write-locked 

Explanation: The output device is not write-enabled. 

User Action: If the output device is a tape, insert a write ring to make it write-enabled. If it 
is a disk, press the write-enable switch on the disk drive. 

BRU — WARNING — Wrong backup set 

Explanation: During a restore operation from a multivolume backup set, BRU foimd that 
one of the tapes or disks does not contain the correct backup set. 

User Action: Specify the correct tapes or disks and reenter the command line. 

BRU — WARNING — Wrong Input volume label 

Explanation: The input volume label specified with the /INVOLUME qualifier does not 
match the volume label of the input device. 

User Action: Specify the correct input volume label and reenter the command line. 

3.10.3 Fatal Error Messages 

BRU issues the following fatal error messages: 

BRU — 'FATAL — Allocation for system file exceeds volume limit 

Explanation: One of the five system files (file type SYS) that are created when a volume is 
initialized does not fit on the output disk. This message usually occurs when the output 
disk is smaller than the input disk. 

User Action: Use the /POSITION qualifier to force allocation to start at the beginning of 
the disk and/or use the /MAXIMUM and /HEADERS qualifiers to reduce the size of 
INDEXF.SYS. 

BRU — 'FATAL* — Ambiguous option 

Explanation: You specified a BRU option that is not unique. For example, the B in 
/POSITION:B could mean either BEGINNING or BLOCK. 

User Action: Use at least three characters to specify a unique form of a BRU option. 

BRU — -FATAL- — Ambiguous qualifier 

Explanation: You specified a BRU qualifier that is not unique. For example, /RE could mean 
either /REVISED or /REWIND. 

User Action: Use at least three characters to specify a unique form of a BRU qualifier. 



Backup and Restore Utility (BRU) 3-51 



BRU — FATAL— Attach failed on ddnn: 

Explanation: You specified a device that BRU cannot access. 

User Action: Use the DCL command SHOW DEVICE or the MCR command DEVICES to 
see if the device is in use (allocated or mounted) by another user. Allocate an available 
device and repeat the operation. 

BRU — 'FATAL* — Bod block data error 

Explanation: An error occurred while reading the bad block information on the output disk. 

User Action: Use the BAD utility (see Chapter 2) to re-create the bad block information or 
use another disk. 

BRU — FATAL — Bad block file full 

Explanation: You entered more than 204io sets of contiguous bad blocks. You cannot enter 
more bad blocks than the bad block file can (BADBLK.SYS) hold. 

User Action: If the number of contiguous bad blocks on your disk exceeds 204io, you can 
no longer use it effectively. Use another disk. 

BAC- -FATAL* — Connof append on continuation volume 

Explanation: The /APPEND qualifier was specified with a continuation volume. A backup 
set can be appended to the first volume only. 

User Action: Mount a blank volume and reenter the command line without the /APPEND 
qualifier. 

BRU — 'FATAL* — Close or write attributes error [dlrectory]fliename.type;verslon 
iO Error code number 

Explanation: During a copy to a mounted volume, BRU encountered an error while 
attempting to close the specified file. 

User Action: Determine the cause of the error from the I/O code (see the 
RSX-llM-PLUS MCR Operations Manual or the RSX-llM-PLUS Command Language Manual). 
If it is correctable, delete the portion of the file that BRU has copied. Then, reenter the 
command line. 

BRU — 'FATAL* — Conflicting qualifiers 

Explanation: Two or more of the specified qualifiers are mutually exclusive; for example, 
/SUPERSEDE and /NOSUPERSEDE. 

User Action: Reenter the command line without one of the mutually exclusive qualifiers. 

BRU — FATAL — Device conflict 

Explanation: You specified both tape and disk drives as part of either the input device 
specification (for a restore operation) or the output device specification (for a backup 
operation). 

User Action: Specify a single type of device (that is, either a tape or a disk drive) and reenter 
the command line. 
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BRU — FATAL- — Device not in system 

Explanation: A device was specified that is not known to the sy: em. 

User Action: To obtain a list of the devices currently available, use the SHOW DEVICE 
command. Specify a device that is known to the system and reenter the command line. 

BRU — -FATAL* — Device not mounted (lies 1 1 on ddnn: 

Explanation: The BRU qualifiers specified on the command line cannot be used unless the 
device is mounted with the Files-11 format. 

User Action: Mount the device Files-11 and reenter the command line, or use a different 
command line. (For a list of the correct combinations of mounted devices and qualifiers, 
see Table 3-1.) 

BRU — FATAL — Device not mounted foreign on ddnn: 

Explanation: The BRU qualifiers specified on the command line cannot be used unless the 
device is mounted foreign. 

User Action: Mount the device foreign and reenter the command line, or use a different 
command line. (For a list of the correct combinations of mounted devices and qualifiers, 
see Table 3-1.) 

BRU — -FATAL- — Device not supported 

Explanation: You specified a device that is not supported by the operating system. 

User Action: Check the command line for valid device names. Then, correct any errors and 
reenter the command line. 

BRU — -FATAL- — Directive error 

Explanation: An internal error occurred in BRU. This may indicate that pool is low. 

User Action: Reenter the command line. If the problem recurs, there may be a problem 
with your software. 

BRU — -FATAL- — Disl< read error 

Explanation: An unrecoverable read error occurred on the output disk, possibly caused by 
an undetected bad block, or an error occurred while BRU was sizing the input or output 
disk. 

User Action: Use the BAD utility to locate all bad blocks on the output disk. Then, reenter 
the BRU command line. 

For information on the BAD utility, refer to Chapter 2. 
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BRU — -FATAL' — Disk write error 

Explanation: An unrecoverable write error occurred on the output disk. The error could 
have been caused by an undetected bad block. 

User Action: Use the BAD utility to locate all bad blocks on the output disk. Then, reenter 
the BRU command line. 

For information on the BAD utility, refer to Chapter 2. 

BRU — 'FATAL* — Doubly deflned qualifler 

Explanation: You specified the same qualifier more than once on the command line. 
User Action: Specify the qualifier only once and reenter the command line. 

BRU — -FATAL' — End Of volume encountered. Backup set not found. 

Explanation: You specified a backup set that is not on the tape or disk volume. 

User Action: Mount the correct tape or disk volume. If you have the correct volume 
mounted, specify the correct backup set name and reenter the command line. 

BRU — FATAL' — Error limit exceeded 

Explanation: BRU reached the maximum number of read errors allowed and terminated 
execution. 

User Action: Using a different tape drive, reenter the command line. If you do not have 
another drive, clean the tape drive heads on the original drive. Then, reenter the command 
line. 

BRU — "FATAL' — Error reading command file 

Explanation: An I/O error occurred while BRU was reading the indirect command file. 
User Action: Reenter the command line. 

BRU — FATAL — Failed to read bad block file 

Explanation: BRU was unable to read the bad block information from a last-track output 
disk. 

User Action: Use the BAD utility (see Chapter 2) with the /OVR switch to locate all bad 
blocks. Then, specify the /BAD:OVERRIDE qualifier and reenter the command line. 

BRU — 'FATAL' — File ID exceeds maximum number of flies 

Explanation: You specified a maximum number of files with the /MAXIMUM qualifier that 
was smaller than a file ID encountered on the input volume. 

User Action: Specify a larger value with the /MAXIMUM qualifier and reenter the command 
line. 
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BRU — FATAL— File not found 

Explanation: You specified an indirect command file or backup set file that BRU could not 
find. 

User Action: Specify the correct file name and reenter the command line. 

BRU — FATAL — Handler not resident 

Explanation: You specified a device that does not have a driver loaded in memory. 

User Action: Load the driver for the specified device. If the driver you intended to use is 
currently loaded, then specify the correct device name and reenter the command line. 

BRU — 'FATAL — Header read error [directory]tllename.type;version 
lO error code number 

Explanation: During a restore operation, an I/O error occurred while BRU v*ras reading a file 
header in the index file. The operation terminates. 

User Action: See the RSX-llM-PLUS MCR Operations Manual or the RSX-llM-PLUS 
Command Language Manual for a definition of the error code number. 

BRU — 'FATAL* — Home block write error 

Explanation: An unrecoverable I/O error occurred while BRU was writing the home block 
on the output device. 

User Action: Before initializing the disk, use the BAD utility (see Chapter 2) to find all the 
bad blocks. Then, reenter the BRU command line. 

BRU — 'FATAL' — Illegal use of directory qualifier 
Explanation: You specified one of the following: 

• The /DIRECTORY qualifier with a disk or tape that is not part of a backup set 

• The /INI qualifier (or one of its related qualifiers) with the /DIRECTORY qualifier 
User Action: If you are initializing a device, do not use the /DIRECTORY qualifier. 

BRU — FATAL — Inconsistent /INITIALIZE qualiHers 

Explanation: You specified the /NOINITIALIZE qualifier with one or more of the initializa- 
tion qualifiers for the output disk. 

User Action: Reenter the /NOINITIALIZE command line without using any of the 
iiutialization qualifiers. 

BRU — 'FATAL' — Index file header read error 
lO error code number 

Explanation: An I/O error occurred while BRU was reading the header of the index file on 
the input disk. 

User Action: For a definition of the I/O error code number, see the RSX-UM-PLUS MCR 
Operations Manual or the RSX-llM-PLUS Command Language Manual. Reenter the command 
line. 
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BRU — FATAL — Index file write error 

Explanation: An I/O error occurred while BRU was writing the index file on the output disk. 

User Action: Use the BAD utility (refer to Chapter 2) to identify the bad blocks on the 
output disk; then, reenter the command line. 

BRU FATAL INDEXF.SYS is full 

Explanation: The index file (INDEXF.SYS) cannot map any more file headers. 

User Action: Specify larger values for the /MAXIMUM and /HEADER qualifiers and reenter 
the command line. 

BRU — -FATAL — Input device equals output device 

Explanation: The input and output devices must be different. 

User Action: Specify different input and output devices and reenter the command line. 

BRU — 'FATAL* — Input line too long 

Explanation: The maximum length of a command line is 256io characters. 

User Action: Truncate qualifiers and options to shorten the line. Make sure the truncated 
forms are unique. All BRU qualifiers are unique to three characters; all options are uruque 
to two characters. 

BRU — "FATAL — Internci error 

Explanation: BRU has detected an error v«thin itself. 

User Action: Reenter the command line. If the problem recurs, there is a problem with your 
software. 

BRU — 'FATAL- — invoiid dote or time 

Explanation: You specified an incorrect date or time in the command line. 
User Action: Specify the correct date or time and reenter the command line. 

BRU — FATAL — Invalid density 

Explanation: This error occurs for one of two reasons: 

• You specified a density tape that was not 1600 (the default), 800, or 6250 bpi. 

• You attempted to use both 7-track and 9-track tapes in a multivolume tape set. 

User Action: If you specified the wrong density, reenter the command line with the correct 
density. For a multivolume tape set, use one type of tape (7 track or 9 track). 

BRU — FATAL — Invalid disk format 

Explanation: If you were performing an /IMAGE:RESTORE operation, you mounted a disk 
that is not a multivolume backup disk. If you were performing an /IMAGE:SAVE operation, 
you attempted to append to a disk that is not a multivolume backup disk. 

User Action: Mount the correct disk and reenter the BRU command line. 
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BRU — •FATAL' — Invalid tape format 

Explanation: An invalid tape record was read during a restore operation. 
User Action: No user action is required. The invalid record is not restored. 

BRU — "FATAL* — Invalid filename 

Explanation: The name of the indirect command file is not syntactically correct. 
User Action: Reenter the command line with the correct file name. 

BRU — 'FATAL — Invalid value or name 

Explanation: A value or name specified for a qualifier has illegal syntax or is out of range. 
User Action: Refer to the description of the qualifier to determine the correct values for it. 

BRU — 'FATAL' — Manufacturer bad sector file is corrupt 

Explanation: BRU was unable to read the bad block information from a last-track output 
disk. 

User Action: Using the BAD utility with the /OVR switch, check the disk for bad blocks. 
Then, specify the /BAD:OVERRlDE qualifier and reenter the command line. 

BRU — FATAL — MFD read error 

Explanation: An I/O error occurred while BRU was reading a block of the Master File 
Directory (MFD). BRU cannot copy the directories or files in that block of the MFD. 

User Action: Reenter the command line. If the header still cannot be read, the files on the 
disk are "lost." Use the File Verification Utility (VFY) with the /LO switch to recover the 
lost files (refer to Chapter 14). 

BRU — 'FATAL — Mlssing colon 

Explanation: A qualifier option that accepts a value was not followed by a colon. 
User Action: Reenter the command line and include the missing colon and value. 

BRU — 'FATAL' — More than 1 level of indirection 

Explanation: BRU does not support more than one level of indirect command files. You 
cannot nest indirect command files when you are using BRU. 

User Action: Specify an indirect command file that does not use other command files and 
reenter the command line. That is, use only one level of indirect command files. 

BRU — FATAL — Name exceeds maximum allowed length 

Explanation: You specified a name (such as a backup set name) that is longer than 
12 characters. 

User Action: Specify a name that is less than 12 characters. 
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BRU — FATAL — Number of headers inconsistent with maximum (lies 

Explanation: Diiring an attempt to initialize an output volume, you specified a maximum 
number of files (/MAXIMUM) that is inconsistent with the number of headers specified 
with the /HEADERS qualifier. 

User Action: For the valid ranges of values for the /MAXIMUM and /HEADERS qualifiers, 
see the description of the INITIALIZE command in the RSX-llM-PLUS MCR Operations 
Manual or the ^X-llM-PLUS Command Language Manual. 

BRU — -FATAL — Open error [directory](llename.type:version 
lO error code number 
File ID number 

Explanation: During a copy operation to a mounted volume, an error occurred while BRU 
was attempting to open the specified file. 

User Action: See the I/O error codes in the RSX-llM-PLUS MCR Operations Manual or the 
RSX-1 IM-PLUS Command Language Manual for a definition of the error code number. If the 
error is correctable, delete any portion of the file already copied by BRU. Then, reenter the 
command line. 

BRU — FATAL* — Output disk too fragmented to restore 

Explanation: The internal tables in BRU have overflowed because of extreme fragmentation 
of the output disk. If the output disk was initialized, then it has an unacceptable number 
of bad blocks and should not be used as a backup medium. 

User Action: Use a new disk as the output device. 

BRU — FATAL — Output device is full 

Explanation: There are no free blocks on the output disk. This can occur when the output 
disk is smaller than the input disk or during an append to a tape or disk that is already full. 

User Action: Use another output disk or tape with more free space, or reenter the command 
line with a subset of the files specified. 

BRU — -FATAL* — Override invalid with non-last-traci< device 

Explanation: The /BAD:OVERRIDE qualifier is valid only when the output disk is a last-track 
device. 

User Action: For information on the /BAD qualifier, see Section 3.3.3. 

BRU — FATAL— Privilege violation 

Explanation: The mount status of one of the devices is inconsistent with the qualifiers 
specified in the command line. For example, the device may be mounted FOREIGN, but 
the qualifiers you used apply to Files-11 devices only. 

User Action: Check the mount status of the device. Then, reenter the command line with 
the appropriate qualifiers (see Table 3-1). 
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BRU — 'FATAL* — Ran out of spare file IDs 

Explanation: The output disk required more file headers than the input disk, but no free 
headers were available. The lack of headers is probably due to one of the following two 
reasons: 

• The output disk is too fragmented because of bad blocks. 

• There are no free file headers on the input disk. 

User Action: If you do not need to preserve file IDs, reenter the command line, with the 
/NOPRESERVE qualifier specified. 

If you want to preserve file IDs, do one of the following: 

• If the output disk is too fragmented, use the BAD utility (refer to Chapter 2) to display 
the number of bad blocks. If it contains a large number of bad blocks, use a different 
disk. 

• Use the PIP switch /FR (see Chapter 12) to display the number of free file headers on 
the input disk. If there are fewer than four free headers, delete some of the files and 
reenter the command line. If you still do not have enough file headers, specify the 
/NOPRESERVE qualifier in the command line. 

BRU — 'FATAL' — Required input device missing 

Explanation: The input device was not specified on the command line or in response to the 
prompt. 

User Action: Reenter the command line. 
BRU — 'FATAL' — Required output device missing 

Explanation: The output device was not specified on the command line or in response to 
the prompt. 

User Action: Reenter the command line. 
BRU — 'FATAL' — Rewind error on ddnn 

Explanation: An I/O error occurred during a tape rewind. This error is fatal if it occurs on 
the first tape of a tape set or during a rewind for a verify operation. The error is not fatal 
if BRU is rewinding a tape it is finished with. 

User Action: If the error is fatal, reenter the command line. If the error is not fatal, no user 
action is required. 

BRU — 'FATAL — Search for tiome block failed 

Explanation: The home block could not be found on the input disk. Either the home block 
is bad or the disk is not in FUes-ll format. 

User Action: Check to see that you have the correct disk. 
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BRU — 'FATAL* — Stack overflow in sort routine 

Explanation: BRU has detected an error within itself. 

User Action: Reenter the command line. If the problem recurs, there is a problem with your 
software. 

BRU — -FATAL' — Syntax error 

Explanation: The comntiand line is invalid. 

User Action: Use valid syntax and reenter the command line. 

BRU — 'FATAL — Tape iabel error on ddnn 
lO Error code number 

Explanation: An I/O error occurred while BRU was writing a tape label on the first tape of 
an append operation. 

User Action: Specify a different tape and reenter the command line. 

BRU — FATAL — Tape not at BOT. No rewind or append specified 

Explanation: For a backup operation to tape, unless you specify the BRU qualifier /APPEND, 
BRU does not process a tape that is not at the beginning of the tape (BOT). 

User Action: If you want to start writing at the beginning of the tape, use the /REWIND 
qualifier. 

You can append to tape only at the end of the last backup set. If the tape is already 
positioned there, specify the /APPEND qualifier in the command line. If it is not positioned 
at the end of the last backup set, specify both the /REWIND and /APPEND qualifiers in 
the command line. 

BRU — 'FATAL' — Tape positioning error. Bacicspace faiied. 

Explanation: During a backup operation, the tape was not positioned properly for a future 
append operation. 

User Action: Rewind the tape by using /REWIND before attempting the append operation. 

BRU — 'FATAL' — Tape positioning error. No EOV encountered. 
i/O Error code number. 

Explanation: The tape spacing operation failed to find the end-of-tape (EOT) volume for an 
append operation. 

User Action: Reenter the command line. 

BRU — 'FATAL — Tape read error 

Explanation: A nonrecoverable I/O error occurred whUe BRU was reading a tape. BRU 
terminates the operation. 

User Action: No user action is required. 
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BRU — •FATAL- — Tape to tape not supported 

Explanation: BRU does not back up a tape to another tape. 
User Action: Use a fixed disk to perform a backup operation. 

BRU — 'FATAL- — Too many devices 

Explanation: You may specify only one disk drive as an input device for a backup operation 
or as an output device for a restore operation. 

Up to eight tape drives may be specified as output devices for a backup operation or as 
input devices for a restore operation. If the /IMAGE qualifier is specified, up to eight disk 
drives may be specified as output devices for a backup operation (/IMAGE :SAVE) or as 
input devices for a restore operation (/IMAGErRESTORE). 

For a disk-to-disk operation, only one disk drive may be specified as an input device and 
only one disk may be specified as an output device. 

User Action: Specify the correct number of drives and reenter the command line. 

BRU — -FATAL- — TOO many file specifications 

Explanation: You specified more than 16 file specifications on the command line. 

User Action: Reenter the command line. To reduce the number of file specifications on the 
command line, use wildcards. 

BRU — -FATAL- — UFD or MFD requires unsupported extension headers 

Explanation: BRU does not support extension headers for Master File or User File directories 
(MFDs or UFDs, respectively). 

User Action: Reenter the command line. If the problem recurs, there is a problem with your 
software. 

BRU — FATAL — Unknown option 

Explanation: You specified an option that BRU does not recognize. 

User Action: Check the qualifiers and options, and then reenter the command line. 
BRU — -FATAL- — Unknown qualifier 

Explanation: You specified a qualifier that BRU does not recognize. 

User Action: Check the qualifiers and reenter the command line. 

BRU — FATAL — Unsupported structure level 

Explanation: The file structure level on the input disk is not supported by BRU. 

User Action: Check to be sure you have placed the correct disk in the drive. 

For more information on file structures, see the descriptions of the /HEADERS and 
/MAXIMUM qualifiers. 
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BRU — FATAL — VBN not In nie 

Explanation: A file ID was encountered that is larger than the maximum file ID in the index 
file. The file is ignored. This error message occurs if a directory entry was corrupted on the 
input disk. 

User Action: No user action is required. 

BRU — FATAL — Verify lost 

Explanation: During the verify pass, BRU lost synchronization between the input and the 
output. Either the tape position was lost, or you backed up from a disk that was changed 
during the backup operation. 

This error can occur when files are created, deleted, or renamed during the backup operation; 
BRU is unable to verify the data on the output device. The message can also indicate a 
hardware error. 

User Action: Be sure the contents of the input disk do not change during the data transfer or 
verify operations. Before repeating the operation, be sure there is no activity on the disk. If 
you are backing up or restoring the system disk, be sure there is no activity on the system 
(such as Resource Accounting and error logging). Then, reenter the command line. 

BRU — -FATAL — Volume not a backup tape 

Explanation: The tape mounted for an append or restore operation was not generated by 
BRU, or the tape is not positioned correctly for an append operation. 

User Action: Check to see that you have the correct tape. Then, reenter the command line. 

If you have the correct tape, reenter the command line with the /REWIND qualifier to 
position the tape. 

BRU — FATAL — Volume not ready 

Explanation: The device is not on line. 

User Action: Put the device on line and reenter the command line. 

BRU — -FATAL — Volume write-locked 

Explanation: The output device is not write-enabled. 

User Action: If the output device is a tape, insert a write-ring to make it write-enabled. If it 
is a disk, press the write-enable switch on the disk drive. 

BRU — 'FATAL — Wrong backup set 

Explanation: During a restore operation from a multivolume backup set, BRU found that 
one of the tapes or disks did not contain the correct backup set. 

User Action: Specify the correct tapes or disks and reenter the command line. 
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BRU — FATAL — Wrong input volume label 

Explanation: The input volume label specified with the /INVOLUME qualifier does not 
match the volume label of the input device. 

User Action: Specify the correct input volume label and reenter the command line. 
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Chapter 4 

File Compare Utility (CMP) 



The File Compare Utility (CMP) compares two ASCII text files. The maximum record length of 
the files is 132io. The fUes are compared line by line to determine whether parallel records are 
identical. CMP allows you to perform the following file-compare functions: 

• Generate a listing showing the differences between the two files. Each difference is listed 
as a pair: first, the lines from the first file, and then the lines from the second file. 

• Generate a listing in the form of one list, with differences marked by change bars. 

• Generate output suitable for input to the Source Language Input Program (SLP). This output 
contains the SLP commands and input required to make the first input file identical to the 
second input file. (For more information on SLP, see Chapter 13.) 

CMP provides switches that allow you to control compare processing. Use of these switches 
allows you to control comparison of blanks, tabs, form feeds, and comments. You can also 
control line numbering and specify the number of lines required for CMP to consider that a 
match has been made between lines in the two files. 

4. 1 CMP Command Line 

You can invoke CMP by any of the methods described in Chapter 1. The command line for 
DMP is shown next. 

Format 

[outfile[/svntch[...]]=] infilel,infile2 

Parameters 

outflle 

Specifies the file specification for the output file. 

The format for entering file specifications is as follows: 

ddnn : [directory] filename . type ; version 

Refer to Chapter 1 for detailed descriptions of the parameters for file specifications. 
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This file can be in one of the following three formats, depending on the switch you specify 
in the command line: 

• Differences 
" Change bar 

• SLP command input 

The defaults for outfile are as follows: 

SYO Specifies the user's default system device. 

directory Specifies the directory that CMP is running under. 

FILCOM Specifies the default file name. 

LST Specifies the default file type. 

If you do not specify an output file, the output defaults to your terminal. 

If you do not specify a file version number, the default is the most recent version of the file 
plus one. 

switch 

Specifies switches that you apply to the output file specification. Some of the switches can 
be negated and some are mutually exclusive. Refer to Section 4.1.1 for details on switches. 

infllel 

Specifies the file specification for the input file to be compared to infileZ. The file name of 
this file must be specified. The default file type is MAC. 

infile2 

Specifies the file specification for the input file to be compared to infilel. You do not 
need a complete file specification. The specifications for infilel are used as defaults for any 
unspecified portions of infile2. 

If you type an equal sign (=) but give no output file specification, only the total number of 
differences is output to your terminal. 

Examples 

CMP>FILE1.MAC,FILE2.MAC [M] 

Lists the differences between FILEl.MAC and F1LE2.MAC on your terminal. 

CMP> DB2 : [42 , 10] EXEC ■:2 [RETI 

Interprets the second input file as DB2:[42,10]EXEC.MAC;2. 

CMP>=FILE1.MAC;1,FILE2.MAC;1 HH! 
10 differences found 

Lists the total number of differences. 
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4. 1 . 1 CMP Switches 

Table 4-1 lists the CMP switches, and describes the function of each one. Table 4-2 gives the 
default setting for each one. You specify switches after the output file in the command line. 

Toble4-1: CMP Switches 

Switch Format Function 

/BL Specifies that blank lines in both files be included in compare processing. If this 

[/-BL] switch is specified in the form /-BL, blank lines are not included in compare 

processing. The /-BL switch is ihe default. 

/CB Specifies that CMP list infile2 with change bars, in the form of exclamation 

[/-CB] points (!), to denote which lines do not have a corresponding line in infilel. 

When a section of lines in infilel has been deleted in irvfile2 (the output listing 
file), the first line not deleted is marked. The /-CB switch is the default. 

You can change the change bar character from the exclamation point to any 
character you wish by meaiis of the /VB switch. 

[/CO] Specifies that CMP include comments (that is, text preceded by a semicolon ( ; )) 

/-CO in compare processing. The /CO switch is the default. 

[/Dl] Specifies that CMP list the differences between the two files (rather than marking 

/-Dl the lines in infile2). The /DI switch is the default. 

The /CB and /DI switches are mutually exclusive. If you specify both, the /CB 
switch overrides the /DI switch. 

/FF Specifies that CMP include records consisting of a single form-feed character in 

[/-FF] compare processing. The /-FF switch is the default. 

/Ll:n Specifies that n lines must be identical before CMP recognizes a match. The 

[/Ll:3] /Ll:3 switch is the default. 

When it encounters a match, CMP lists all the preceding nonmatching lines, 
along with the first line of the matched sequence of lines, to help you find the 
location in the code where the match occurred. 

[/LN] Specifies that lines in the output file be preceded by their line number. Line 

/-LN numbers are incremented by one for each record read, including blank lines. 

The /LN switch is the default. If you specify the /SL switch, the /LN switch 

is unnecessary. 

[/MB] Specifies that CMP include all blank and tab characters in a line in compare 

/-MB processing. If you specify the /-MB switch, CMP interprets any sequence of 

blank and/or tab characters as a single blank character. However, all spaces 
and tabs are printed in the output listing. The /MB switch is the default. 

/SL[:au] Directs CMP to generate an output file suitable for use as SLP command input. 

[/-SL] When you specify the /SL switch, CMP generates the SLP command input 

necessary to make infilel identical to infile2. If a 1- to 8-character alphanumeric 
symbol is included in the /SL switch (:au), an audit traU is specified for SLP 
input. Section 4.1.2.3 gives an example of how CMP generates SLP command 
input. (For information on how SLP processes source files, refer to Chapter 13.) 
The /-SL switch is the default. 
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Table 4-1 (Cont.): CMP Switches 



Switch Format Function 



/SP[:n] Specifies that the output file be spooled on the line printer. You can optionally 

[/-SP] specify the number, n, (in octal or decimal) of files to be spooled. The /-SP 

switch is the default. This switch applies only if you have the Queue Manager 

system installed. 

[/TB] Specifies that CMP include all trailing blanks on a line in compare processing. 

/-IB If you specify the /-TB switch, CMP ignores all blanks following the last 

nonblank character on a line. When you specify the /-CO and the /-TB 
switches together, blanks that precede a semicolon (;) are considered trailing 
blanks and are ignored. The /TB switch is the default. 

/VB:nnn Specifies an octal character code for the character you want to use as a change 

[/VB:041] bar. You use this switch with the /CB switch. The value nnn specifies the octal 

character code. For example, you can specify /VB:174 for a vertical bar (if your 

printer is capable of printing the vertical bar character). The default switch is 

/VB:041 for an exclamation point. 

CMP default switch settings are listed in Table 4-2. 

Table 4-2: Summofy of CMP Default Switch Settings 

Switch Function 

/-BL Does not compare blanks. 

/-CB Does not generate change bars. 

/CO Compares comments. 

/DI Lists only the differences between the two files. 

/-FF Does not compare form-feed characters. 

/LI:3 Finds three identical lines before a match occurs. 

/LN Generates numbered lines. 

/MB Compares all blank and tab characters. 

/-SL Does not generate an output file suitable for use as SLP command input. 

/-SP Does not spool the output file. 

/TB Compares all trailing blanks. 

/VB:041 Sets the exclamation point (ASCII 041) as the change bar character (used with the 
/CB switch). 
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4.1.2 Formats of CMP Output Files 

CMP uses the two input files you specify on the command line to create an output file. CMP 
compares each line in infilel to its sequential counterpart in infile2. When there are differences 
between the two files, CMP displays those differences in one of the following three output 
formats: 

• Differences format (/Dl switch) 

• Change bar format (/CB switch) 

• SLP command input format (/SL switch) 

The default is the Differences format. 

Sections 4.1.2.1 to 4.1.2.3 give examples of each of these formats. The following files are used 
as infilel (TEST1.DAT;1) and infile2 (TEST2.DAT;1): 



DB0:[7,7]TEST1.DAT;1 



DB0:[7,7]TEST2.DAT;1 



LINEl 

LINE2 

UNE3 

LINE4 

LINES 

12345 

23456 

34567 

LINE9 

LINEIO 

LINEl 1 

EXTRA 



LINEl 

LINE2 

LINE3 

LINE4 

LINES 

45678 

56789 

67891 

LINE9 

LINEIO 

LINEl 1 

EXTRA 

EXTRA 

EXTRA 

EXTRA 



4.1.2.1 Differences Format 

If you enter a command line and do not specify any switches, CMP lists the differences between 
the two files on your terminal or in an output file. The differences are listed in pairs; first, the 
lines from infilel that do not have counterparts in infile2 are listed, and then the lines from 
infile2 that do not have counterparts in infilel are listed. Each set of lines is terminated by the 
first line (or set of lines) for which a match is successful. 

Refer to Section 4.1.2 for a description of the contents of files TEST1.DAT and TEST2.DAT. 
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Example 

CMP>TESTDIF .DAT=TEST1 . DAT . TEST2 . DAT [ret] 

Contains no switches, and generates the following output file: 



4e*«***:|<* + **«sKs|c*i|i*4<i|<*>I>«>|c*>|c******4i>I<4i*«*****:<c4e«* 


1) 


DB0:[7,7]TEST1.DAT;1 


6 


12345 


7 


23456 


8 


34567 


9 


LINEg 


*iHf************** 


2) 


DB0:[7,7]TEST2.DAT:1 


6 


45678 


7 


56789 


8 


67891 


9 


LINE9 


4i4>«**!|i********s|<«**4c************************s|c* 


1) 


DB0:[7,7]TEST1.DAT;1 


***************** 


2) 


DB0:[7,7]TEyTy.DAT;l 


13 


EXTBA 


14 


EXTRA 


15 


EXTRA 



2 differences found 

The input files are TEST1.DAT and TEST2.DAT. There are two sets of differences separated by 
a long line of asterisks ( * ). (When there are several sets of differences, CMP separates each set 
from the next set by a long line of asterisks.) The short line of asterisks separates the pair of 
differences that comprise the set. 

Note that because the /LI switch was not specified, the number of lines required for a match 
defaults to 3. Thus, CMP found two differences. 

4.1.2.2 Change Bar Format 

You use the /CB switch to generate a listing containing change bars that show the differences 
between two files. In the CMP command line, infile2 is the listing you want generated. 

Refer to Section 4.1.2 for a description of the contents of files TEST1.DAT and TEST2.DAT. 
Example 

CMP> TESTDIF . DAT/CB=TEST1 . DAT . TEST2 . DAT [RET] 

Produces the following output file with change bars applied to lines from two files that do not 
match: 
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2 


LINE2 


3 


LINE3 


4 


LINE4 


5 


LINES 


6 


45678 


7 


56789 


8 


67891 


9 


LINE9 


10 


LINEIO 


11 


LINEll 


12 


EXTRA 


13 


EXTRA 


14 


EXTRA 


15 


EXTRA 



2 differences found 
Notice that the change bar is appUed to the first line of match (line 9). 

4.1.2.3 SLP Command Input Format 

You use the /SL switch to generate a file containing records to be used as SLP command input. 
/SL directs CMP to generate the SLP edit command lines and input lines required to make 
infilel identical to infile2. 

However, you must enter the command line with SLP command input. CMP does not generate 
this command line. For a complete description of the SLP utility, refer to Chapter 13 in this 
manual. 

Refer to Section 4.1.2 for a description of the contents of files TEST1.DAT and TEST2.DAT. 
Example 

CMP>TESTDIF . DAT/SL : BLS001=TEST1 . DAT . TEST2 . DAT [RET] 

Uses the /SL switch to generate the following output file: 

-6.8,/;BLS001/ 

45678 

56789 

67891 

-12.,/;BLS001/ 

EXTRA 

EXTRA 

EXTRA 

/ 



File Compare Utility (CMP) 4-7 



4.2 CMP Messages 

CMP issues two kinds of messages: informational and error. Informational messages provide 
information on the compare operation. 

Error messages describe a condition that caused CMP to terminate the processing of a command. 
When this occurs, CMP returns to the highest level of command input. For example, if the 
command is entered in response to the Monitor Console Routine (MCR) prompt, CMP will issue 
the error message, exit, and prompt you with the MCR prompt, as follows: 

>CMP commandline 
CMP — message 
> 

If the command is entered in response to the CMP prompt, CMP wUl issue an error message 
and prompt you with the CMP prompt, as follows: 

CMP>coiiimandline 
CMP — message 
CMP> 

This section lists the CMP messages, gives a brief description of the condition that causes each 
message, and suggests a response to the condition. 

4.2.1 Informational Message 

CMP issues the following informational message: 

CMP — n differences found 

Explanation: CMP found n differences between the two files. 
User Action: This is an informational message. 

4.2.2 Error Messages 

CMP issues the following error messages: 

CMP — Command syntax error 

Explanation: CMP found an error in the command line syntax. 

User Action: Check the syntax of the command line specification, specify the correct syntax, 
and reenter the command line. 

CMP — Error reading input (iie # 1 

Explanation: An I/O error occurred while CMP was reading the first input file. 
User Action: Reenter the command line. 

CMP — Error reading input file #2 

Explanation: An I/O error occurred while CMP was reading the second input file. 
User Action: Reenter the command line. 
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CMP — Error writing output die 

Explanation: An I/O error occxirred while CMP was writing the output file. The output 
device may be full or bad. 

User Action: Check if the output device is full or bad, and then reenter the command line. 
CMP— Illegal /LI value 

Explanation: You specified a negative value for the number of lines required for a match. 
User Action: Specify a legal value and reenter the command line. 

CMP — illegal switch or switch value 

Explanation: An illegal switch or switch value was entered in the command line. 
User Action: Use a legal switch or switch value and reenter the command line. 

CMP — Open failure on input file # 1 

Explanation: CMP could not open the first input file. 

User Action: Check the file specification for first input file. Use the correct file specification 
and reenter the command line. 

CMP — Open failure on input file #2 

Explanation: CMP could not open the second input file. 

User Action: Check the file specification for second input file. Use the correct file specification 
and reenter the command line. 

CMP — Open failure on output file 

Explanation: CMP could not open the specified output file. 

User Action: Check the file specification for the output file. Use the correct file specification 
and reenter the command line. 

CMP — Too many differences for avaiiabie core 

Explanation: The files were too dissimilar for CMP to fit all the differences in memory. 

User Action: Remove and reinstall CMP v^th a larger increment. For information on 
the DIGITAL Command Language (DCL) command INSTALL/EXTENSION, refer to the 
RSX-llM-PLUS Command Language Manual. For more information on the Monitor Console 
Routine (MCR) command INSTALL, refer to the RSX-llM-PLUS MCR Operations Manual. 
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Chapter 5 

File Dump Utility (DMP) 



The File Dump Utility (DMP) enables the user to examine the contents of a specific file or 
volume of files. The output may be formatted in ASCII, octal, decimal, hexadecimal, or 
Radix-50 form and dumped to any suitable output device such as a line printer, terminal, 
magnetic tape, DECtape, or disk. 

You can dump the header and/or virtual blocks of a file, portions of blocks, or the virtual 
records of a file. If you are dumping a volume, a range of logical blocks may be specified (see 
Sections 5.1.1 and 5.1.2). DMP normally handles blocks of up to 256io words in length. If the 
maximum block size exceeds 256io words, DMP's buffer size must be increased as follows: 

>RUN $DMP /INC=n [M] 

The value of the variable n must be equal to a multiple of 8 that is equal to or greater than the 
maximum length block or record minus 256io words. 

The same restriction applies when dumping records greater than 512io bytes. In this case, you 
must increase DMP's buffer size by altering the DMPBLD.CMD or DMPANSBLD.CMD file as 
required and by rebuilding the task. See the appropriate system generation manual and your 
system manager for more specific information on altering various featiu-es of DMP. 

5. 1 DMP Command Modes 

DMP operates in two basic modes: file mode and device mode. File mode is used to dump 
virtual records or virtual blocks, and device mode is used to dump logical blocks. 
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5.1.1 File Mode 

In file mode, one input file is spedfied, and all, or a specified range, of the virtual blocks 
are dumped. You can also dump all the virtual records of a spedfied fiile in this mode. The 
input device must be either a Files-11 formatted disk or a magnetic tape. The volume must be 
mounted by using the Monitor Console Routine (MCR) or DIGITAL Command Language (DCL) 
command MOUNT. 

Note 
If the input medium is magnetic tape, DMP must be built with ANSLIB instead 
of SYSLIB. 

In file mode, you can spedfy that data be dumped one record or one block at a time. A virtual 
block or record refers to one block or record of data in a file. Virtual blocks and records are 
numbered sequentially from 1 to n, where n is the total number of blocks or records in the file. 
Use the /BL switch to dump virtual blocks and the /RC switch to dump virtual records. The 
/BL and /RC switches are mutually exdusive. (DMP switches are listed in Table 5-1.) 

5.1.2 Device Mode 

In device mode, only the input device is specified, and a spedfied range of logical blocks is 
dumped. The /BL switch is a required parameter in this mode. 

A logical block refers to a physical 512-byte block on disk or DECtape and to physical records 
on magnetic tape or cassette. Logical blocks are numbered from to n-1, where n is the total 
number of logical blocks on the device. The volume must be mounted foreign. 

5.2 DMP Command Line 

You can invoke DMP by using any of the methods described in Chapter 1. The command line 
for DMP is shown next. 

Format 

[outfile][/switch[...]][=inspec][/switch[...]] 

Porameters 

outflie 

Spedfies the output file. The format for entering file spedfications is as follows: 

ddnn : [directory] filename . type ; version 

Refer to Chapter 1 for detailed descriptions of the parameters for file specifications. 

If the output file name and file type are unspecified, DMP creates the file DMPFIL.DMP. If 
the file type is DMP, the file will be deleted after it is printed. The TI and LP devices (for 
terminal and line printer) are also acceptable outfile specifications. 

When you spedfy LP as your output device, the data to be printed is written into an 
intermediate file and then the file is given to the Queue Manager, which handles the 
spooling. 



5-2 File Dump Utility (DMP) 



switch 

Specifies one of the switches listed in Table 5-1. Unless otherwise indicated in a switch 
description, all switches can be applied either to the input file or to the output file with 
equal effect. DMP will allow multiple dumps in a single command line. Therefore, any or 
all of the current format switches may be specified. Certain switches are mutually exclusive. 
For example, the /HX, /LW, and /WD switches are mutually exclusive hexadecimal dump 
switches. The first switch in the following order will be the only one executed: /LW, /WD, 
and /HX. 

inspec 

Specifies the input device and file or input device only (refer to the previous description of 
outfile for the format of file specifications). In file mode, the equal sign (=) and the input 
file name and file type are required because DMP does not provide a default for either of 
them. However, the input file version number defaults to the latest version and the device 
defaults to SY and the current directory. 

In device mode, the equal sign and input device are required, as is the /BL switch, which 
specifies the range of logical blocks to be dumped. 

5.2. 1 DMP Switch Descriptions 

DMP switch specifications consist of a slash ( / ) followed by a switch name, which is optionally 
followed by a value. The value is separated from the switch by a colon ( : ). DMP functions are 
implemented by the switches listed in Table 5-1. 

Table 5- 1 : DMP Switches 



Switch Format Function 



Default The default is a word mode octal dump, which is spooled to the line printer. 

/AS Specifies that the data should be dumped one byte at a time in ASCII 

mode. The control characters (0-37) are printed as a circumflex ("), which 
is followed by the alphabetic character corresponding to the character code 
plus 100. For example, bell (code 7) is printed as "G (code 107). Lowercase 
letters (140-177) are printed as a percent sign (%), which is followed by 
the corresponding uppercase letter (character code minus 40), unless the /LC 
switch is specified. 

Note that the /AS and /OCT switches are mutually exclusive when dumping 
bytes. 
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Table 5-1 (Cont.): DMP Switches 



Switch Fonnat Function 



/BA:n:in Specifies a 2-word base block address (the initial base address is 0,0), where 

n is the high-order base block address (octal), and m is the low-order base 
block address (octal). The address may also be specified in decimal by using 
a period (.) after the number. All future block numbers specified by the 
/BL switch will be added to this value to obtain an effective block number. 
This switch is useful for spedf5dng block numbers that exceed 16 bits. For 
example: 

DMP>/BA:1:0 [Ml 

The previous command line specifies that all future block numbers will be 
relative to 65536io (ZOOOOOg). 

DMP>/BA:0:0 [M] 

The previous command line clears the base address. Once the /BA switch is 
specified, it remains in effect until it is used again to set a new base address. 
When the /BA svntch appears alone in a command line, no blocks are 
dumped. The only result of the command line is to set the base address. 

/BL:n:m Specifies the range of blocks to be dumped, where n is the first block and m 

is the last block. The values of n and m must not exceed 16 bits. In file mode 
only, the /BL switch is not required. If the /BL switch is not specified, DMP 
will dump all blocks of the specified file, which is relative to the current base 
address. 

If /BL:n:m is specified in file mode, it specifies the range of virtual blocks to 
be dumped. If /BL:n:m is specified as /BL:0 in file mode, no virtual blocks 
are dumped. This is useful for dumping only the header portion of the file 
(see the /HD switch). The /BL switch and the /RC switch are mutually 
exclusive. 

The /BL switch is a required parameter in device mode. When used in device 
mode, it specifies the range of logical blocks to be dumped. 

Magnetic tapes and cassettes, when dumped in device mode, are always 
dumped starting with the current tape position. The values given with the 
/BL switch are not used to position the tape. The switch values are used, 
however, to label the pages of the dump listing and to determine the number 
of blocks to dump. 

When a switch value of /BL:n:m is specified, (m-n>+l blocks are dumped, 
starting at the current tape position. The value n represents the block number 
of the first block dumped. Successive blocks are labeled with a block number 
one higher than the preceding block number. The dump will continue until 
the block labeled m is dumped. 

/BY Specifies that the data be dumped in octal byte format. 

/DC Specifies that the data be dumped in decimal word format. 
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Table 5-1 (Cont.): DMP Switches 



Switch Format Function 



/DENS:n 



/FI:n:sequence 

/HD[:F] 
/HD:U 



/HF 



/HX 



Spedfies the density of an input magnetic tape with 800- or 1600-bpi 
capability when DMP is in device mode only. The value for n can be 
800 and 1600. 

DMP does not automatically determine the density of an input tape. If the 
/DENS switch is not specified in a DMP command line, DMP attempts to 
read an input tape at the density currently set in the tape controller. (See 
the ^X-UM-PLUS MCR Operations Manual, the RSX-llM-PLUS Command 
Language Manual, the Micro/RSX User's Guide, Volume 1, and the Micro/RSX 
User's Guide, Volume 2 for descriptions of the MOUNT command and its 
/DENS switch.) 

In file mode, the file number can be used instead of a file name as a file 
specification for input. 

This switch is an optional parameter used in file mode. If specified, the /HD 
switch causes the file header as well as the specified or implied portion of 
the file to be dumped. For example: 

DMP> TI : = JMF . DAT/HD/BL : 5 : 6 [M] 

The previous conunand line dumps the header of JMF.DAT in header format 
and virtual blocks 5 and 6 in octal format. 

In addition, the /HD switch has two options: the default, F, causes a Files- 11 
formatted dump of the header, and U spedfies an unformatted octal dump. 
An octal dump also occurs when DMP is used on non-Files-1 1 headers. 

If you want only the header portion of the file to be dumped, specify the 
following: 

DMP>TI:= JMF. DAT/HD/BL :0 [M] 

File headers are described in the RSX-llM-PLUS and Micro/RSX I/O 
Operations Reference Manual. 

Spedfies the format for data blocks that have the Files-11 header structure. 
Other blocks are output as a data dump in the format selected by svtdtches 
such as /AS and /BY in default octal words. For example: 

DMP>HEAD.LST=[0,0]INDEXF.SYS/HF [M] 

The previous command line generates a dump of the index file INDEXF.SYS 
and formats all the headers in the file. 

Spedfies that the data be diraiped in hexadecimal byte format. Note that 
a hexadecimal dump reads from right to left. (See also the /LW and /WD 
switches.) 
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Table 5-1 (Cont.): DMP Switches 



Switch Format Function 



/ID Causes DMP's version to be identified. This switch may be specified on a 

command line by itself at any time. For example: 

DMP>/ID [M] 

DMP— DMP version M07.1B (ANSI) 

For DMP built with ANSLIB, the response is as follows: 
DMP— DMP version MOT. IB 

/LB Requests logical block information for a file and displays the starting block 

number and a contiguous or noncontiguous indication for the file. For 
example: 



DMP>TI:=DK0:RICKSFILE.DAT;3/LB M] 
Starting block number = 0,135163 C 

The previous command line indicates that the file RICKSFILE.DAT, version 3, 
is a contiguous file starting at block number 0,135163. (See the /BA switch 
for block number description.) 

/LC Specifies that the data should be dumped in lowercase letters. This switch 

can only be used if the output device has lowercase capability. 

/LIM:n:m Specifies the range of bytes n-m of each record or block to be dumped. The 

/OCT switch is still the default if no format switches are specified. 

/LW Specifies that the data be dumped in hexadecimal doubleword format. 

/MD[:n] Specifies a memory dump and allows control of line numbers. Line numbers 

are normally reset to whenever a block boundary is crossed. The /MD 
switch allows lines to be numbered sequentially for the full extent of the file; 
that is, the line numbers are not reset when block boundaries are crossed. 
The optional value n specifies the value of the first line number. The default 
is 0. The /MD switch is used with the output file specification. 

/OCT Specifies that the data should be dumped in octal format in addition to other 

formats specified. If no DMP format switches are specified, the default is 
octal. The /AS switch and the /OCT switch are mutually exclusive when 
dumping bytes. 
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Table 5-1 (Cont.): DMP Switches 



Switch Fonnat Function 



/RC Specifies that data be dumped a record at a time (rather than a block at a 

time). The data format is determined by setting any of these fonnat switches: 
/AS, /DC, /HX, /LW, /R5, or /WD. 

The largest record that DMP can process is limited by the amount of space 
available to the DMP task. DMP's task image has 512 bytes allocated 
to it initially. To increase the amount of space available, use the MCR 
command INSTALL with the /INC switch or the DCL command INSTALL 
/EXTENSIONrn. For example, to dump a file with 1024-byte records, you 
must specify /INC=256io (at least). If the input is a tape and the block 
size is greater than 512 bytes, $FSR1 must be expanded as described in the 
DMPBLD.CMD or DMPANSBLD.CMD file. 

The /RC switch and the /BL switch are mutually exclusive. 

/RW Causes DMP to issue a rewind command before referencing a specified 

tape. This switch may be specified at any time to re-position a tape at the 
beginmng-of-tape (BOT). 

/R5 Specifies that data be dumped in Radix-50-format words. 

/SB:n Specifies the number of blocks DMP spaces forward (n) or backward (-n) on 

/SB:-n tape. DMP stops when it senses end-of-tape (EOT). DMP will space only 

single blocks beyond EOT. 

/SF:n Specifies the number of end-of-file (EOF) marks DMP spaces forward (n) or 

/SF:-n backward (-n) on tape. DMP stops when it senses EOT or BOT. DMP will 

space only single EOF marks beyond EOT. 

/SP Causes the dump output file to be spooled to the line printer. The /SP 

switch may only be specified on the output file specification; it is illegal on 
the input file specification. Spooled files may be deleted after printing. 

/WD Specifies that the data be dumped in hexadecimal word format. 



5.3 DMP Examples 

Three examples of dump listings are included in this section to illustrate how the various DMP 
switches can be used. DMP edits blocks or records 16io bytes at a time. The dump includes 
the indicated number of valid bytes in the block or record. The remaining number of bytes are 
listed as null bytes (0). 

5.3.1 Multiple Format Dump 

The command line shown in Example 5-1 dumps virtual blocks 5 and 6 of DSC.MAC in 
hexadecimal, Radix-50, and decimal format. Each line of the output file will appear in three 
different formats. 
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IDENTIFICATION AREA 



I.FNAM. 










I.FTYP. 










I.FVER 








DSC .MAC;: 


I.RVNO 








1 


I.RVDT 








13-QCT-86 


I.RVTI 








09:52:46 


I.CRDT 








13-0CT-86 


I.CRTI 








09:52:45 


I.EXDT 








— 


MAP AREA 










M.ESQN 








000 


M.ERVN 








000 


M.EFNU. 










M.EFSq 








(0.0) 


M.CTSZ 








001 


M.LBSZ 








003 


M.USE 








014 = 12. 


M.MU 








314 = 204. 


M.RTRV 










SIZE 


LBN 






12. 


H: 


000 


L 


: 036215 = 15501 


3. 


H: 


000 


L 


: 036235 = 15517 


1. 


H: 


000 


L 


: 036250 = 15528 


2. 


H: 


:000 


L 


: 036272 = 15546 


3. 


H: 


:000 


L 


: 036313 = 15563 


11. 


H: 


:000 


L 


: 036411 = 15625 


CHECKSUM 










H.CKSM 


122620 





5.4 DMP Error Messages 

Error messages describe a condition that caused DMP to terminate the processing of a command. 
When this occurs, DMP returns to the highest level of command input. For example, if the 
command is entered in response to the Monitor Console Routine (MCR) prompt, DMP will 
issue the error message, exit, and prompt you with the MCR prompt, as follows: 

>DMP commandline 
DMP — message 
> 

If the command is entered in response to the DMP prompt, DMP will issue a error message 
and prompt you with the DMP prompt, as follows: 

DMP>commandline 
DMP — message 
DMP> 

The error messages for DMP are as follows: 

DMP — Bad device name 

Explanation: An incorrect device name was entered in a file specification. 
User Action: Specify the correct device and reenter the command line. 
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DMP — Block switch required in ioglcai biocic mode 
Explanation: The /BL switch must be specified. 
User Action: Specify the /BL switch and reenter the command line. 

DMP — Cannot find input fiie 

Explanation: The requested file cannot be located in the specified directory. 

User Action: Specify the correct file name and directory and reenter the command line. 

DiVIP — Command syntax error 

Explanation: A command line was entered in a format that does not conform to syntax rules. 
User Action: Specify the correct S5mtax and reenter the command line. 

DMP — Faiied to read attributes 

Explanation: A file was specified for which you did not have read access privileges. 

User Action: Rerun DMP under a User Identification Code (UIC) that has read access 
privileges to the file. 

DMP — Illegal density value 

Explanation: A value other than 800 or 1600 bpi was specified with the /DENS switch. 
User Action: Specify the correct density and reenter the command line. 

DMP— Illegal switch 

Explanation: A switch was specified that is not a valid DMP switch, or a legal switch was 
used in an invalid manner. 

User Action: Specify the correct switch and reenter the command line. 

DMP — Illegal use of /RC switch 

Explanation: The /RC switch can be used only in file mode (see Section 5.1.1). 
User Action: Specify a file name and reenter the command line. 

DMP — Illegal value on /HD switch 

Explanation: An option was entered other than F (the default) or U (the unformatted octal 
dump) for the /HD switch. 

User Action: Specify the correct option and reenter the command line. 
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DMP — I/O error on input (lie 
or 

DMP — I/O en-or on output file 

Explanation: One of the following conditions exists: 

• A problem exists on the physical device (for example, the device cycled down). 

• The file is corrupted or the format is incorrect. 

• The output volume is full. 

User Action: Determine which condition caused the message and correct that condition; 
then, reenter the command line. 

DMP — No input file specified 

Explanation: A command line was entered with no input file specification. 
User Action: Specify an input file and reenter the command line. 

DMP — No lists or wild cards allowed 

Explanation: Either a command line with more than one input or output file name was 
entered, or a wildcard was entered as a file specification. 

User Action: Specify only one input file specification and one output file specification, and 
reenter the command line without wildcard specifications. 

DMP — Open failure on indirect (lie 

Explanation: The requested indirect command file does not exist as specified. One of the 
following conditions exists: 

• The file is protected against access. 

• A problem exists on the physical device (for example, the device cycled down). 

• The volume is not mounted. 

• The specified file directory does not exist. 

• The named file does not exist in the specified directory. 

User Action: Determine which condition caused the message and correct that condition; 
then, reenter the command line. 
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DMP — Open failure on input file 
or 

DMP — Open failure on output (lie 

Explanation: One of the following conditions exists: 

• The file is protected against access. 

• A problem exists on the physical device (for example, the device cycled down). 

• The named file does not exist in the specified directory. 

• The volume is not mounted. 

• The specified file directory does not exist. 

User Action: Determine which condition caused the message and correct that condition; 
then, reenter the command line. 
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Chapter 6 

Disk Save and Compress Utility (DSC) 

The Disk Save and Compress Utility (DSC) copies a Files-11 disk either to disk or to tape and 
from DSC-created tape back onto disk. At the same time, DSC reallocates and consolidates the 
disk data storage area: it concatenates files and their extensions into contiguous blocks whenever 
possible and, therefore, reduces the number of retrieval pointers and file headers required for 
the same files on the new volume. 

DSC copies files that are randomly scattered over a disk volume to a new volume, without the 
intervening spaces. This eliminates unused space between files and reduces the time required 
to access them. 

6. 1 DSC Operations 

A complete DSC operation is a cycle that begins with data on one disk and ends with the 
same data in compressed form on another disk. The operation can use one command (for a 
disk-to-disk cycle) or two commands (for a disk-to-tape and tape-to-disk cyde). You can use 
DSC on line or stand alone. The standalone version of DSC is included in BRUSYS.SYS (refer 
to Chapter 3 for more information). 

After a DSC copy operation, individual files are written in available contiguous blocks and the 
blocks available for new files are located in a contiguous area at the end of the new volume. If 
the contents of one disk are transferred to a disk with a larger capacity, the new disk takes on 
the attributes of the original disk, except that additional storage space is available. 

DSC reads and writes data to its two buffers when it performs copy or compare operations. 
(See Figures 6-1 and 6-2.) Each buffer normally is large enough to contain four disk blocks 
and a 16-byte buffer prefix. However, the Block Factor switch (/BL) in a DSC command line 
allows you to increase the number of blocks in each buffer, up to the maximum space available 
for DSC on your system. 

In a disk-to-disk copy operation, DSC performs the following tasks: 

1. Copies data from disk to a DSC buffer 

2. Copies data from the DSC buffer to another disk 
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Figure 6-1: Data Transfer for DSC Copy Operation 



Blocks of Data 



DSC 
Buffer 1 



DSC 
Buffer 2 





Disk Input Device 




Disk Output Device 



O DSC reads eight (default) or more blocks of data from the disk input device to two 
buffers. 

In disk-to-tape copy operations, DSC writes data from the buffers to magnetic tape. 

In disk-to-disk copy operations, DSC writes data from the buffers to the disk output 
device. 

DSC repeats steps O and © or © until it copies tiie entire input device. 

ZK-1 82-81 
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Figure 6-2: Data Transfer for DSC Compare Operation 

Blocks of Data 





Disk Input Device 





Disk Output Device 



V DSC reads four blocks (default) of data from the disk input device to a buffer. 

tSf DSC reads four blocks (default) of data from the disk output device to the second buffer. 

© DSC compares the contents of the two buffers. 

© DSC prints the differences on your terminal. 

DSC repeats steps O to O until it tias compared ttie entire device. 



ZK-183-81 



In a disk-to-tape and tape-to-dislc operation, DSC performs the following tasks: 

1. Copies data from disk to a DSC buffer 

2. Writes data from the DSC buffer to tape 
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3. Copies data from tape to a DSC buffer 

4. Writes data from the DSC buffer to another disk 

You can execute operations 3 and 4 to restore data to disk at any time. 

After a disk-to-disk copy operation, you can access the data on the new disk directly. However, 
after a disk-to-tape operation you cannot access the data on tape directly because it is stored in 
a format recognizable only to DSC. To access this data, you must perform a second DSC copy 
operation and transfer the data to another disk volume. 

When DSC copies and compresses a disk containing a saved system (a task image file created 
from an RSX-llM-PLUS system image by the Monitor Console Routine (MCR) command 
SAVE), it moves all task files to different physical addresses. However, because the Task 
Control Block (TCB) entries for each task contain file identifications rather than Logical Block 
Numbers (LBNs), such a saved system can function normally when it is rebooted. 

You can also use DSC to recover from hardware malfunctions that have made a portion of a 
disk volume uru-eadable. If the contents of a block allocated to a data file cause a read error, 
you can use DSC to copy the garbled contents to the output device and to generate a warning 
message labeling the garbled data block. You can then access the block and correct its contents. 



6.2 DSC-Supported Volumes 

You can use DSC with a variety of mass storage or magnetic tape devices. The status DSC 
requires for the devices varies with the operating system. DSC requires volumes to be mounted 
with foreign characteristics. 

Table 6-1 lists the devices that can be used vdth DSC operations. 
Table 6-1: DSC-Supported Devices 



Abbreviation Type 



Class 



DB 

DD 

DF 

DK 

DL 

DM 

DP 

DR 

DS 

DT 



RP04/RP05/RP06 disk pack 

TU58 cassette (DECtape II) 

RFll/RSll fixed-head disk 

RK05/RK05F cartridge disk 

RL01/RL02 cartridge disk 

RK06/RK07 cartridge disk 

RP02/RP03 disk pack 

RM02/RM03/RM05/RM80/RP07 disk pack 

RH70/RS03/RS04 and RH70/RS03 fixed- 
head disk 

TU56 DECtape 



Block structvired 
Block structured 
Block structured 
Block structured 
Block structured 
Block structured 
Block structured 
Block structured 
Block structured 

Block structured 
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Table 6-1 (Cont.): DSC-Supported Devices 



Abbreviation T)rpe Class 

DU RA80 fixed media disk Block structured 

DX RXOl diskette Block structured 

DY RX02 diskette Block Structured 

MM TE16/TU16/TU45/TU77 9-track magiietic Tape 

tape 

MS TSll magnetic tape Tape 

MT TUIO/TEIO 7- or 9-track magnetic tape Tape 

TS03 9-track magnetic tape 

6.3 DSC Command Line 

You can invoke DSC by any of the methods described in Chapter 1 of this manual. The 
command line for DSC is shown next. 

Format 

outdev[,...][melabell][/switch[...]]=indev[,...][filelabel2][/switch[...]] 

Parameters 

outdev 

Specifies the physical volume or volumes to which data is copied. The format for outdev is 
as follows: 

dd[im] : 

The parameter dd specifies the American Standard Code for Information Interchange (ASCII) 
characters for the volume abbreviation, and [nn] is an optional 1- or 2-digit octal unit number 
for the volume. The colon ( : ) is required syntax for a device specification. If you omit the 
unit number, is the default. 

DSC uses tape drives in the order specified in the command line. If more tapes are required 
than specified, DSC accesses the tape drives available in round-robin fashion. Up to eight 
tape drives, separated by commas ( , ), can be specified as output devices in a DSC operation. 

DSC ignores multiple disk specifications. 

fllelabell 

Identifies the output disk's Volume ID, the tape file, or the tape set that DSC creates in a 
data transfer. You can specify a file label with either disk or tape output volumes. If you 
do not specify a file label, and you copy a disk to tape, DSC records the Volume ID of the 
input disk on the tape. When you copy from tape to disk, the output Volume ID defaults 
to the ID recorded on the tape. In a disk-to-disk copy operation, the output Volume ID will 
defavilt to the ID of the input disk. 
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switch 

Specifies one or more of the optional switches described in Table 6-2. (For detailed 
descriptions of the switches, refer to Section 6.5. 

indev 

Specifies the physical volume or volumes, in the same format as outdev, from which data 
is copied. 

fllelabel2 

Identifies the DSC-created tape file that is being transferred to disk or is being compared. 
If you do not specify a file label, DSC transfers the first file it encounters after its current 
position on the tape. DSC ignores the specification of an input file label when the input 
volume is a disk. 



Note 

Each file on a DSC-created tape set contains the contents of the disk copied by DSC. 

Table 6-2: DSC Switches and Options 



Switch 



Format 



Description 



Append /AP 



Bad Block 



/BAD=< 



MAN 

NOAUTO 

MAN:NOAUTO 

OVR 

MAN:OVR 



Block Factor 

Compare 

Density 

Rewind 
Verify 



/BL=n 
/BL:n 

/CMP 



/DENS= 

/DENS: I 1600 ,„, 
' I 800:1600 

/RW 
/VE 



Appends a DSC file to the first volume of a tape 
set that already contains a DSC file. The latter file 
is currentiy the last file of the set. 

Allows manual entry of bad block locations; it 
can supplement, override, or ignore the disk's bad 
block file. 



Sets the number of 256-word blocks DSC can 
include in each of its two buffers. 

Compares input and output volumes for differ- 
ences. 

Overrides the DSC default storage density for 
magnetic tapes of 800 bpi. 



Rewinds all magnetic tapes before DSC executes 
the current command. 

Copies data from the input volume and compares 
it vnth data in the output volume. 



6.4 File Labels 

The file label identifies the data copied from a disk and stored on one or more tapes or on 
another disk. If you do not specify a file label, DSC uses the Volume ID of the input disk 
volume label as the output volume label. 
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The file label can consist of from 1 to 12 alphanumeric characters. However, when copying to 
tape, DSC uses nine characters to identify the file it creates, which contains the disk's contents. 
Place the file label after the device specification and before any switches. Terminate the file 
label with one of the following: 

• An option switch 

• An equal sign (indicating the end of the output side of the command line) 

• A carriage return (indicating the end of the command line) 

Examples 

DSOMMOl : , MM02 : SYSFILE=DB1 : [RET] 

Uses the file label SYSFILE in the command line to identify the file on tape that will contain 
the data to be copied from the input disk, DBl. 

You can also use the file label when restoring data from tape to disk. If you enter a file label as 
part of the input specification, DSC searches the first volume for a file with that name. When it 
finds that file, DSC transfers it to the output volume. If, however, you do not specify an input 
file label, DSC transfers the first DSC-created file it locates on the first input volume. In both 
cases, use of the Rewind switch (/RW) on the input side of the command causes the tape to be 
rewound before the search for the file starts. 

If you use a file label as part of the output specification, it will be used as the volume label of 
the output disk. If you do not specify an output file label, the default file label is that of the 
original input disk (as recorded in its home block). 



DSODBl : =MM01 : . MM02 : SYSFILE [RET] 

Because the /RW switch was not specified on the input side, DSC searches the first volume 
specified, MMOl, beginning at the current position, for a DSC-created file named SYSFILE. If 
DSC finds SYSFILE on MMOl, it completes the data transfer. If, however, SYSFILE is not found 
on the first volume, DSC issues an error message and terminates the operation. 

If you enter the command line without a file label, DSC transfers the first DSC-created file it 
finds to DBl regardless of the file name. (This file may or may not be SYSFILE.) If you do not 
specify the /RE switch, the tape may or may not be positioned at the beginning before DSC 
begins its operation. 

6.5 DSC Switch Descriptions 

DSC commands can contain file labels and switches. Some switches also use options to specify 
values. This section describes in detail the functions of the DSC switches. Table 6-2 summarizes 
the DSC switches and options. 
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6.5.1 Append 

The Append switch (/AP) directs DSC to begin writing a file to the first specified volume of a 
tape set that contains only DSC-created files. 

Enter the /AP switch as part of the output specification. The volume to which files will be 
appended must be specified as the first volume of the output side of the command line. 

When you use the /AP switch with the output specification, DSC searches from the current 
position on the first specified tape output volume for the last logical end-of-file (EOF) created 
by a previous DSC command. If the last DSC-created file does not end on that volume, DSC 
terminates the operation and issues the following message: 

Output tape ddnn: is full 

If the first specified tape output volume contains a portion of a DSC file that began on a previous 
volume, DSC terminates the operation and issues the following error message: 

Output tape ddnn: is a continuation tape 

If DSC locates the end of a file on the tape that began on another volume, DSC terminates the 
operation and issues the following error message: 

Output tape ddnn: is not the only reel in its set 

Example 

DSO MMOl : , MM : SYSF ILE/RW/ AP=DXi : fRET] 

Appends the contents of DXl to the last DSC-created file already present on the first output 
volume specified, MMOl. Because the Rewind switch (/RW) is specified (see Section 6.5.6), 
DSC first rewinds the tape on MMOl and searches for the last EOF block on the tape. When it 
determines that only complete DSC-created files exist on the volume on MMOl, DSC appends 
the new file, SYSFILE, to the file or files already on the tape. If necessary, DSC extends SYSFILE 
to additional volumes. 

You can only use the /AP switch with output tape volumes. Any other use of the switch causes 
DSC to generate an error message and terminate the operation. 

6.5.2 Bad Block 

Use the Bad Block switch (/BAD) with output disk volumes to control the way DSC uses bad 
block information. 

The options for the /BAD switch allow you to perform the following tasks: 

• Supplement the output disk bad block file with manually entered bad block data. 

• Ignore or override the bad block file on last track (manufacturer's list of bad blocks) or 
non-last-track devices. 

• Use only manually entered bad blocks. 

The bad block descriptor of the disk is never altered by DSC. 
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If the /BAD switch is not specified, DSC will access the bad block descriptor area (the last good 
block on non-last-track disks or the entire last track on last-track disks) to obtain the information 
to create the bad block file, BADBLK.SYS. If DSC determines that the descriptor area is invalid, 
DSC displays a warning message (see Section 6.8.1, Message 59). 

Format 

/BAD=option 

Parameter 

option 

Specifies one of the five possible options as follows: 

MAN Supplements the bad block file BADBLK.SYS vwth manually entered 

bad block data. This option may be combined with either NOAUTO or 
OVR. 

NOAUTO Ignores the bad block descriptor area on the disk. Note that in this case, 

DSC will attempt to write in any block it selects. This option may be 
combined vrith the MANUAL option. 

MAN:NOAUTO Enters only manually entered bad block data in the bad block file 
BADBLK.SYS. Thus, DSC bypasses only manually entered bad blocks 
when selecting blocks to write in. 

OVR Ignores the bad block descriptor area and accesses the substitute 

descriptor area (the last good block on the next to the last track on 
the disk) to obtain the data for the creation of the bad block file 
BADBLK.SYS. This option is valid only on last-track devices. This 
option may also be combined with the MAN option. 

MAN:OVR Allows manual entry of bad block data to the bad block file 

BADBLK.SYS. 

When you specify the MAN, MAN:NOAUTO, or MANrOVR option with the /BAD switch, 
DSC responds with the following prompt: 

DSC>LBN(S)= 

DSC issues this prompt after it accepts the original command line but before it transfers any 
data. 

Enter the locations of bad blocks after the LBN(S)= prompt in the format shown next. 

Format 
n:m 

Parameters 
n 

Specifies the logical block number (LBN), in octal, of the initial bad block in the group. 
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m 

Specifies the number, in octal, of consecutive blocks contained in the group. If you do not 
specify m, it defaults to 1. 

To specify a decimal number for either m or n, place a period ( . ) after the number. 

You can specify multiple bad block entries on one command line by using either a space, tab, 
or comma ( , ) to separate each entry. You can also use separate lines for each entry. 

After you enter the first group of bad blocks, DSC reissues the LBN(S)= prompt. At this point, 
you can enter additional bad blocks. 

To terminate manual bad block entry, press the RETURN key after the LBN(S)= prompt. 

When you have entered all the bad blocks and terminated the entry process, DSC begins the 
data transfer. 

Examples 

DSODBl : /BAD=MAN : NOAUTO=MM01 : . MM02 : SYSFILE/RW [Ml 
DSOLBN f S) =702 : 7 fTAB]644 : 2 \M\ 
DSC>LBN(S)=4057.5001:3 Wf] 
DSOLBN (S)=rRETl 
DSO 

Restores the output disk, DBl, from the tape file SYSFILE contamed on MMOl and MM02, 
skipping only the blocks you entered manually. In the previous example, the following blocks 
will not be used: 



702 


644 


4057 


5001 


703 


645 




5002 


704 






5003 


705 








706 








707 








710 









DSO DB 1 : /BAD=N0AUT0=DBO : mil 

Transfers data to the lowest LBNs on DBl regardless of the content of the resident bad block 
descriptor. 

If you specify /BAD=OVR on a last track device, DSC reads the last good block written by the 
Bad Block Locator program (BAD) on the next to the last track of the device. The information 
in this substitute descriptor block is used to create the bad block file. If MAN:OVR is specified, 
manually entered blocks will be added to the bad block file. 
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6.5.2. 1 Obtaining Bad Blocl< Information 

You can obtain bad block information in the following two ways: 

• By running the Bad Block Locator program (BAD), described in this manual 

• By running the DIGITAL Field Service standalone diagnostic 

The BAD utility automatically provides bad block information and creates a bad block file that 
DSC can use. 

The Field Service standalone diagnostic reads every word in a block and displays bad block 
messages on the console terminal. (This diagnostic is recommended for the user who wants 
more comprehensive testing of a volume). However, since the output is the physical address of 
each bad block, you must convert this address to LBNs before DSC can use it. 

6.5.2.2 Conversion to Logical Block Numbers 

All DSC bad block information must identify bad blocks by LBN. 

The manufacturer-furnished or diagnostic bad block information usually identifies bad blocks by 
physical address (sector-track-cylinder). Before you enter this information manually for DSC, 
convert the physical addresses to LBNs. Use the following formula: 

( ( (cylinder number*tracks/cyllnder) -^tracknumber) *sector8/track) +8ector number 

For example, suppose a bad sector of an RP06 (19 tracks per cylinder and 22 sectors per track) 
has the following physical address: 

Octal Decimal 



Cylinder Number 


536 


350 


Track Number 


16 


14 


Sector Number 


13 


11 



The LBN for the example is calculated as follows: 

(( (350. *19.)+14.)*22.)+11. =146619. 

6.5.3 Block Factor 

The Block Factor switch (/BL) allows you to set the number of blocks DSC uses in each of its 
buffers during I/O operations. The default DSC block factor is four blocks or the last value 
specified with the /BL switch. 

Format 

/BL=n 

or 

/BL:n 
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The value of n can be any positive integer, decimal or octal, less than or equal to the maximum 
block factor available to DSC. This maximum depends on the amount of memory DSC can 
access under the system configuration. (See your system manager for this information.) The 
/BL switch can be specified either on the input or output side of a DSC command line. 

Note, if the input volume is tape, DSC determines the block factor from the header label of the 
input file and ignores the /BL switch. 

If you specify the /BL switch on both sides of a DSC command line with a disk volume, 
DSC uses the last value it receives, that is, the one from the input side of the command line. 
However, if you specify the /BL switch only on the output side of a command line, DSC uses 
that value. 

DSC requires 20208 bytes of memory for each additional block of buffer space you specify. If 
the /BL switch in a DSC command line requires more memory than DSC has available, DSC 
displays the message "Bad blocking factor" and exits. 

Example 

DSC>DB1:/BL=11=DB0: [RET] 

or 

DSC>DB1:/BL:11=DB0: [M] 

Attempts to increase the number of blocks in each of DSC's buffers to 11. DSC requires an 
additional 161608 bytes of memory for the expansion (7 additional blocks times 20208 bytes). 

If DSC does not have access to 161608 additional bytes of memory on your system, it will 
display the error message "Bad blocking factor." 

If the expansion succeeds, DSC reads and writes 11 blocks of data at one time during an I/O 
operation instead of 4. This decreases the time required for DSC operations. 

Once DSC has expanded its buffers to the value of the /BL switch, that value becomes the 
default value. DSC does not reduce its task image size if a command line is executed at a lower 
block factor. However, if you specify a lower block factor in a subsequent command line, DSC 
will create that volume at the lower factor. 

6.5.3.1 System-Dependent Requirements for the /BL Switch 

DSC expands automatically if memory is available. (See the RSX-UM-PLUS System Generation 
and Installation Guide for details on building DSC with additional memory.) 

For the RSX-llM-PLUS operating system, the defauU blocking factor is 4, the maximum DSC 
size is 32K words, and the maximum blocking factor is 32io. 
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6.5.4 Compare 

The Compare switch (/CMP) directs DSC to compare the contents of two disks or a disk 
and a tape set. Multiple tape specifications are valid, but multiple disk specifications are not. 
The /CMP switch is always specified on the output side of the DSC command line. If the 
comparison involves tape and disk, specify the tape as the input device. The /CMP switch 
performs only comparison operations; no copy operation is involved. 

To perform both a copy and compare operation, use the DSC Verify switch (/VE) (see 
Section 6.5.7). 

When DSC finds a difference between the volumes it is comparing, it displays a warning message 
on your terminal. This warning message lists the output volume number, file identification, 
and the virhial block number (VBN) where the difference was found. DSC then continues the 
comparison. 

When DSC detects an end-of -volume (EOV) on any reel or end-of-file (EOF) on other than the 
first reel of a tape set, the /CMP switch causes DSC to rewind and unload the current volume 
and resume comparison with the next volume until it detects an EOF. 

When DSC begins a comparison involving tape, it first positions the specified or implied file as 
described in Section 6.5.6. DSC positions a single volume tape at the end of the current file 
when the comparison ends. Each reel of a tape set is rewound and unloaded as the compare 
operation for it is completed. DSC then resumes the comparison by using the next volume of 
the set. 

6.5.5 Density 

The Density switch (/DENS), with its two options, allows you to override the DSC defauh 
storage density of 800 bpi for TU16, TE16, TU77, and TU45 tape drives. The following two 
sections discuss these options. Although you can use other tape drives with DSC, only these 
drives can support the /DENS switch. 

Format 

/DENS=option 

or 

/DENS:option 

Parameter 

option 

Specifies one of the following two options: 

1600 
800:1600 
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The 1600 option creates magnetic tapes at 1600 bpi density and the 800:1600 option (the Split 
Density option) creates magnetic tapes with volume headers at 800 bpi and the rest of the tape 
at 1600 bpi. 

Note that the 1600 option is valid v^th TU16, TU77, TE16, or TU45 drives. The 800:1600 
option is valid with TU16 or TU45 drives only when they are not controlled by the TM03 
formatter. 

You do not have to specify the /DENS switch when a tape is the input device. DSC determines 

the density of all input tapes by first reading the tape at 800 bpi and then, if that fails, reading 

it at 1600 bpi. 

If you specify the /DENS switch with a disk, DSC issues an error message and halts the 

operation. 

If you specify the /DENS switch with tape drives other than those above, DSC ignores the 
switch and does not alter the default density. Note that TSll (TS04) drives write all tapes at 
1600 bpi and caimot support the 800:1600 option. The TSll (TS04) ignores the /DENS switch; 
therefore, do not use it with these devices. 

6.5.6.1 1600 Option 

The 1600-bpi option directs the TU16, TE16, TU77, or TU45 drive to operate as an output 
volume at a density of 1600 bpi. The drive then writes all volumes in the tape set at that 
density. 

Example 

DSOMMOl : ,MM02 : SYSFILE/RW/AP/DENS=1600=DB1 : [M] 
Writes MMOl and MM02 at 1600-bpi density. 

6.5.5.2 Split Density Option 

The Split Density option (800:1600) directs the TU16 or TU45 drives (using the TM02 tape 
formatter) to write the entire tape set, except for the first two blocks on the first volume, at 
1600 bpi. The first block on the file contains the volume label and the second block is a dummy 
boot block that displays the following error message if an attempt is made to boot the volume: 

This volume does not contain a bootable system 

Exomple 

DSOMMOl ; . MM02 : SYSFILE/RW/DENS=800 : 1600=DB1 : [Ml 

Records the first two blocks of the first volume at 800 bpi and the remainder of the file at 
1600 bpi. 

Note 

Magnetic tapes created by using the Split Density option do not comply wdth 
American National Standard Institute (ANSI) X3.27-1978. 

You cannot use the Split Density option with the TE16 magnetic tape drive. Tape drives 
controlled by a TM03 also cannot use the Split Density option. The TM02 controller, however, 
does support the Split Density option. 
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6.5.6 Rewind 

The Rewind switch (/RW) directs DSC to rewind all volumes in a tape set before performing 
any other DSC operation, such as a copy or a compare operation. You can use it to rewind 
either input or output volumes (see Table 6-3). 

The /RW switch can be used only with magnetic tapes. If you use it with any other volume, 
DSC prints an error message. 

If you enter the /RW switch as part of the input specification, DSC rewinds only the first tape 
before the DSC operation begins. The other tapes are rewound before they are about to be 
accessed. If you specify a file label with the /RW switch, DSC rewinds the tapes and searches 
for the file you specified from the beginning-of-tape (BOT) on the first volume. If you do not 
specify a file label, DSC transfers the first DSC-created file it encounters on the first volume. 

After a volume of a tape set has been copied, DSC rewinds it and places it off line. If, however, 
the current file ends on the first or only tape of a set, the tape is positioned to read the next file 
on the input tape. The /RW svdtch only rewinds tapes at the beginning of a DSC operation. 

If you enter the /RW switch as part of the output specification, DSC rewinds the output tape 
before beginning a copy or compare function. The default is no rewind and the tape is not 
moved. 

If you do not enter the /RW switch vdth the output specification and the first volume is not 
positioned at BOT, DSC begins its operation after the last DSC-created end-of-file (EOF) it finds 
on that volume. 

After the output tape has been rewound, DSC determines if the tape is positioned at BOT. For a 
compare function, a search for the next file or a specific file begins at the current tape position. 
For a copy function, if the /AP switch was specified or if the tape is not positioned at BOT, the 
search for the current end of DSC created files begins (see Section 6.5.1); otherwise, the copy 
operation will overwrite any data previously stored on the tape. 

Table 6-3 summarizes the use of the /RW switch with various DSC operations, with and 
without a file label. 



Table 6-3: The Rewind Switch and DSC Operations 
Switch Specification File Label Function 



/RW Input/output With/without 



/RW Input 



/RW Input 



With 



Without 



Rewinds first tape before copy operation 
begins. 

DSC searches for specified file from the 
beginning of the first tape volume before 
a copy/compare operation begins. 

DSC copies/compares the first file it en- 
counters on the first volume. 
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Table 6-3 (Cont.): The Rewind Switch and DSC Operations 



Switch Specification File Label 

/RW Output 



Function 



With 

File labels specified when 
tape is the output vol- 
ume are ignored when 
the tape is restored to 
disk. 



/-RW Output 



DSC writes data, starting at the beginning 
of the first tape volume, unless the /AP 
switch is specified. 



If the tape is not at BOT, DSC writes 
data, beginning after the last EOF block 
it encounters. (If tape is already at BOT, 
and the /AP switch is not specified, DSC 
starts there.) During copy operations to 
multiple tapes, DSC rewinds the tape as it 
is filled and takes it off line. 



Note 

When you refer to tapes after your system is booted, you must use the /RW switch. If you do 
not use the switch, the tape driver will return an error message. 

Examples 



DSOmmOI : SYSFILE/RW=DB1 ; [Ml 

Rewinds the volume on drive MMOl and overwrites any data on the tape. The contents of 
DBl are written to a single file identified as SYSFILE. DSC does not rewind the tape when the 
operation is finished unless the file extends to another volume. If the file does extend, DSC 
rewinds and unloads the filled tape. DSC ensures that subsequent tapes are at BOT before 
using them for read or write operations. Each subsequent volume, including the last one in the 
tape set, is rewound and unloaded when it is filled. 

fRETl 



DSOdBI : =MM02 : . MMOl : SYSFILE/RW 

Restores a volume (DBl) by using a tape set created by a previous DSC operation. DSC rev^dnds 
the first volume on MM02 and searches for a previously created DSC file labeled SYSFILE. If 
the file is found, DSC transcribes it. If it is not found on MM02, DSC issues a message and 
terminates the operation. DSC will not search MMOl if the file does not begin on MM02. Each 
volume of the tape set is rewound and unloaded when the data it contains has been copied or 
compared. If SYSFILE ended on MM02 the first time it was accessed, the tape is not rewound 
and unloaded but is positioned to access the next file. 
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6.5.7 Verify 

The Verify switch (/VE), entered as part of the output specification, directs DSC to perform a 
copy operation followed by a compare operation to verify that the two volumes are the same. 
(DSC does not allow you to specify either the /VE or /CMP switch if both input and output 
volumes are tape.) 

If either the input or output volume is tape, the verify operation takes place at the end of the 
copy operation for each volume. In other words, DSC writes MMOl and compares MMOl, then 
writes MM02 and compares MM02, after which the entire DSC operation is complete. In a 
disk-to-disk DSC operation, the verify operation begins when the copy operation is finished. 

If you do not specify a file label for an input tape set, DSC will copy the first file it finds on 
the first volume of the set. 

When DSC detects the end-of-volume (EOV) or end-of-file (EOF) on any volume of a tape set 
during a copy operation, it re-positions the volume to the beginning of the current file segment 
and begins the verify operation. 

During a verify operation, if DSC detects EOV on any volume, or EOF on other than the first 
volume of a tape set, it rewinds and unloads tiie tape when the operation is complete. After an 
EOV, the copy operation resumes using the next volume from the beginning of the tape. 

Note 

If you specify a tape as one of the volumes, DSC requires exti-a time after the copy operation 
to rewind the tape and search for the current file before it begins to verify. 

6.6 DSC Operation Overview 

DSC initially accesses the first primary fUe header and writes the blocks mapped by its retrieval 
pointers to the output volume. DSC then checks the primary file header to determine whether 
it points to any extension headers. If extension headers exist, DSC ti'anscribes them and the 
blocks they map until the entire file, with all of its extensions, has been written to the output 
volume. DSC then accesses the remaining primary file headers in numerical order. 

Example 

DSC>DB1:=DB2: fRET] 

Copies all the files on DB2 to DBl. 

When DSC copies file extensions, it updates the output retiieval pointers and file linkages 
involved in the ti-ansfer as required. This update not only involves collapsing retiieval pointers, 
but it also reduces the number of file extensions required as the retrieval pointers are eliminated. 

As a result of a copy operation, each primary file header is followed by all of its extensions. 
Volumes created in a copy operation have complete files written to contiguous blocks (except 
where blocks have been flagged as bad in earlier operations on the volume). DSC writes data, 
beginning at the lowest logical block number (LBN) possible on the disk. 

If an input file is contiguous, DSC will search for an area on the output volume with enough 
contiguous blocks to contain the file. If no such area exists, DSC will issue an appropriate 
message and terminate the copy operation. 
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If an input file is not contiguous, data is allocated in as few contiguous sections as possible in 
the first unoccupied blocks available on the output volume. 

Before the actual copying of data to a disk begins, DSC must, in effect, initialize the disk. This 
process might take several minutes if there is a maximum number of files allocated in the index 
file. Although it might appear that DSC is in a loop during this period, it is actually zeroing 
out all headers in the index file. 

6.7 DSC Data Transfers 

As outlined in the beginning of this chapter, DSC's complete data transfer process consists of 
either a direct disk-to-disk operation or a two-step, disk-to-tape/tape-to-disk operation. DSC 
reads and writes data to and from its own internal buffers during these operations. 

The following sections describe DSC's operation in each of these data ti-ansfers. 

6.7.1 Data Transfer from Disk 

After you enter a DSC command line and specify a copy operation from a disk, DSC scans the 
input disk to ensure that it is in Files-11 format. DSC begins by copying an approximation 
of the disk index file. Because this file is updated to reflect the stahis and location of blocks 
as they are allocated on the new disk, the index file bit map, the storage bit map file, and 
the bad block file are not transcribed exactly: DSC tiranscribes only the data necessary for ihe 
consbiiction of these files on the new disk. However, the index file bit map still reflects the 
maximum number of files on the input disk. 

DSC accesses the input volume index file's active file headers in numerical order to locate the 
next active primary file header. DSC fa-ansfers that header, the blocks it maps, and all extension 
headers and related blocks that are part of the file, to the output medium. It then accesses the 
next active primary file header from the index file. DSC continues this operation, each time 
writing a complete file, until it has fa-ansferred all the active files. 

DSC accesses and b-anscribes only the blocks allocated to active files. It ignores unallocated 
blocks interspersed throughout the input disk. This results in contiguous data blocks on the 
output disk following the copied files. 

If DSC accesses a file that contains bad data, DSC transcribes whatever it reads firom the block. 
When DSC restores the file to disk, it writes the block's contents as it originally read them. 
The logical block still contains garbled data, but the new physical block can be accessed and its 
contents corrected. A message identifying these bad areas is displayed on the console terminal. 

In summary, to ti-ansfer data from a disk, DSC performs the following tasks: 

1. Verifies that the disk is on line and in Files-11 format. 

2. Transcribes disk index files updated for their new status. 

3. Reads the data to a DSC buffer. 
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6.7.2 Data Transfer to Tape 

When the output volume in a DSC operation is tape, DSC writes the contents of the input disk 
to a tape on the drive you specify. This data transfer usually involves multiple reels of tape (a 
tape set) and multiple tape drives. 

The tapes that DSC creates serve as a backup of the disk's contents. You can only use DSC- 
created tapes by copying them back to a disk and by restoring the disk's contents to their 
original form. Although the tapes contain many individual files from the input disk, DSC treats 
the tapes as if they contained a single file — a file of the disk's entire contents. 

When DSC begins writing the disk's contents to tape, it allows vmting to more than one volume. 
The first block DSC writes to tape is a header that contains the volume name (obtained from 
the file label) and the relative volume number. This header identifies the tape set and the 
volume's place within that set. It ensures that when DSC begins to restore the disk, it will load 
each volume in the tape set in order. After the header, the tape set includes the data required 
to reconstruct directory files, maps and pointers, and the actual files copied from the disk. 

Note 

When the disk is restored, the directory files are at the beginning of the disk, 
regardless of their position on the original disk. 

To initiate the copy operation, first ensure that the tape devices are on line. You can specify 
multiple tape drives in the following way: 

DSC>ddnn(0) : .ddnn(l) : . . . .dclim(7) : [filelabel]=indev[, . . .] 

You have the option of entering a file label in this command line after you specify the last 
device. While you can specify only one type of tape drive, either MM-, MT-, or MS-type in a 
single DSC command line, you can specify up to eight individual drives on the output side of 
the command line; you can specify each drive only once. 

If the number of volumes in the tape set exceeds the number of tape drives available, DSC uses 
volumes on the specified drives in round-robin fashion. 

Example 

DSOMMO : . MMl : . MM4 : , MM2 : SYSFILE=DB 1 : [RETI 

Shows the order of replacement used until an end-of-file is reached as follows: 

MMO: MMl: MM4: MM2: MMO: MMl: MM4: MM2: ... 

In summary, to transfer data to tape, DSC performs the following tasks: 

1. Verifies that the first or only volume of a tape set is on line and write-enabled. 

2. Verifies that subsequent volumes of a tape set are at beginning-of-tape (BOT), on line when 
required, and write-enabled. 

3. Transcribes data from a DSC buffer to the tape. 
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6.7.3 Data Transfer from Tape 

DSC can only use the tapes it creates to (1) reconstruct a disk or (2) perform compare and 
verify operations. 

When you mount the tapes and specify tape drives as input devices, DSC sequentially accesses 
and writes the tape contents to the output volume. Up to eight drives may be specified on the 
input side; they will be referenced in round-robin fashion as described in Section 6.7.2. As it 
transfers the data, DSC creates and updates directory files. 

Tape drives specified as input devices must be on line. The volumes in the tape set must be 
referenced in the correct order in the command line. If you specify a file label, DSC transfers 
only the contents of the file identified by that label. If you do not specify a file label, DSC 
transfers only the first DSC-created file it encounters on the first volume of a set. 

In summary, to transfer data from tape, DSC performs the following tasks: 

1. Verifies that the tape drives are on line. 

2. Accesses the volumes in a tape set in round-robin order. 

3. Creates directory files. 

4. Reads the data to a DSC buffer. 

6.7.4 Data Transfer to Disk 

A DSC operation is not complete until the data involved in the transfer is restored to disk. 

To receive input, a disk must be on line. Any disk large enough to contain all the input data 
can be specified as the output disk when the data is restored to the original disk. 

The disk should have an up-to-date bad block descriptor or have bad block data entered in a 
DSC command line with the /BAD switch. This ensures that the data written on the disk will 
be accessible. You can update the bad block descriptor before a DSC operation by running the 
BAD program (see Chapter 2). 

After identifying the bad blocks on the output disk, DSC examines that disk to ensure that it 
has enough free blocks to contain all the data to be transferred. DSC compares the number of 
blocks to be transferred from the input disk or disks with the number of blocks available on 
the output disk. DSC issues an error message and exits if too few blocks are available. 

DSC constructs the index and storage bit map files when it begins transcribing files. It updates 
the file headers to reflect the location of the data on the new disk. This updating is required 
because blocks that were previously scattered are now copied to a contiguous set of blocks, 
beginning at the lowest LBN available on the disk. DSC will write the primary file header, 
its contents, and associated file extension headers and the extensions they map as a unit to a 
contiguous series of blocks. Note that the output disk contains an index file of the same size 
as the original disk. This is especially important when the contents of a large disk (such as an 
RP04) are restored to a smaller disk (such as an RK05) or when the contents of a small disk 
(such as an RK05) are restored to a large disk (such as an RP04). 
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Compressing files in this manner is beneficial when retrieval pointers for a noncontiguous 
file header are almost used up. Because DSC creates each retrieval pointer to map as 
many contiguous blocks as possible (the maximum is 256io), the number of pointers may 
be significantly reduced. DSC can also reduce the number of file extensions and extension 
headers. 

Note that when DSC writes to a disk, it begins writing data into the lowest LBN possible. Free 
blocks generally have higher LBNs and are in a contiguous section of the disk. 

The data presently on the disk is overwritten by the new data. Therefore, you cannot use 
DSC to transfer the contents of several small disks to a single large disk. Each copy operation 
eliminates whatever data previously occupied the disk. 

In summary, to transfer data to a disk, DSC performs the following tasks: 

1. Verifies that the disk is on line. 

2. Verifies that the disk has an up-to-date bad block descriptor or that bad blocks are specified 
manually (through the /BAD=NOAUTO switch). Displays a warning message if no bad 
block information is available and the /BAD switch was not specified. 

3. Verifies that the disk has enough free blocks to contain all the data to be transferred. 

4. Creates index and directory files (in the first part of the disk). 

5. Writes the data firom a buffer. 

6.8 DSC Messages 

DSC notifies you of fatal error conditions as well as less serious error conditions that could 
cause difficulties in DSC operations. Each message generated by DSC is identified by a numeric 
code and has the following prefix: 

DSC ~ 

DSC messages are displayed on your terminal in either a long or short form. Online DSC 
displays the long form, and standalone DSC displays the short form. You can determine the 
meaning of the short form messages from the number provided with the message. Use the 
number to find the long form message in Section 6.8.1. The text accompanying the long form 
message of that number explains the error. Also, in order to identify the error, the command 
line or the command line segment may be displayed after the error text. 

Table 6-4 is a quick reference to the single-letter codes used in general error messages and in 
I/O error messages (Section 6.8.2). 
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Table 6-4: General Error and I/O Error Message Codes 



Type of Code Symbol Meaning 



General 


Code A 


Error 


CodeB 


Message 


Codec 
CodeD 




CodeE 




CodeF 


I/O 
Error 


A 
B 


Message 


C 
D 




E 




F 




G 




H 




I 




J 
K 




L 




M 




N 




O 



Failed to read storage bit map header 

Input data out of phase 

Nondata block encountered 

Input file out of phase 

File attributes out of phase 

File header out of phase 

Reading index file bit map 
Reading index file header 
Reading storage bit map 
Reading boot or home block 
Reading file header 
Input (or output device) 
Writing index file bit map 
Writing storage bit map header 
Reading data 
Reading input tape labels 
Reading file attributes 
Reading file header 
Reading index file data 
Reading summary data 
Writing file header 



When DSC identifies a file in which a problem has been detected, it provides only the file 
ID (file number, file sequence number) of that file. Use the Dump utility (DMP) (described in 
Chapter 5) with the File switch (/FI) and the Header switch (/HD) to obtain the name of the 
file and other information contained in the file header. 

Example 

DSC>TI:=devid:/FI:x:y/HD/BL:0 [Ml 

Outputs to a terminal the header or headers of file x, y. The variables x and y, displayed in 
certain DSC error messages, represent the file number and file sequence number respectively. 

6.8. 1 DSC Error Messages 

DSC error messages may or may not be fatal. Fatal error messages are displayed in the following 
format: 

DSC — *FATAL* message 

Error messages describe a condition that caused DSC to terminate the processing of a command. 
When this occurs, DSC returns to the highest level of command input. For example, if the 
command is entered in response to the Monitor Console Routine (MCR) prompt, DSC will issue 
the error message, exit, and prompt you with the MCR prompt, as follows: 

>DSC commandllne 
DSC — message 
> 
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If the command is entered in response to the DSC prompt, DSC will issue an error message 
and prompt you with the DSC prompt, as follows: 

DSOconimandline 
DSC — message 
DSO 

The following are the general error messages DSC can return: 

2 Conflicting dev. types 

Explanation: An illegal combination of device types was specified. 

User Action: Check for typographical errors in device abbreviations and make sure that the 
disks and tape drives are not specified on the same side of the command line. 

3 Mixed tape types 

Explanation: Two different types of tape drives were specified in the command line. 
User Action: Specify only one type of tape drive and reenter the command line. 

4 illegal switcii 

Explanation: The command line was entered with a svdtch that cannot be used with that 
command line. 

User Action: Specify only correct switches and reenter the command line. 

5 File label too long 

Explanation: A file label consisting of more than 12io alphanumeric characters was specified. 
User Action: Specify a shorter file label and reenter the command line. 

6 Syntax error 

Explanation: An error occurred in the command line format. 

User Action: Specify the correct order and reenter the command line. 

7 Dup. dev. name; 

Explanation: The same device was entered more than once in the command line. 
User Action: Specify each device only once and reenter the command line. 

8 Too many dev's 

Explanation: More than the legal number of devices were specified on one side of the 
command line. 

User Action: Specify no more than eight devices per side and reienter the command line. 
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9 Dev. ddnn: not in system 

Explanation: The specified device is not present in the configuration of the operating system 
being used. 

User Action: Check the device identifier that was entered in the command line. Specify an 
appropriate device and reenter the command line. 

10 Dev. ddnn: not FILES- 11 

Explanation: The specified input device is not formatted as a Files-11 device. 

User Action: Check the input device that wras entered in the command line. Specify an 
appropriate device and reenter the command line. 

1 1 Bad block syntax error 

Explanation: A syntax error occurred when bad block data was manually entered. 

LZscr Action: Check the command line that was entered and reenter the correct command 

line. 

12 Bad block count too large 

Explanation: There are too many groups of bad blocks (the maximum is 125io) on the output 

disk for DSC to handle. 

User Action: Use a different output disk. 

1 3 Bad block cluster out of range 

Explanation: A manually entered bad block or group of bad blocks does not exist on the 
output disk. 

User Action: Check the numbers of the blocks entered. Specify the correct block numbers 
and reenter the command line. 

15 Output tape ddnn: full 

Explanation: The specified tape is full and files cannot be appended to it. 

User Action: Change the output tape and reenter a command line to begin a new tape set. 

16 Output tape ddnn: not only reel In set 

Explanation: The /AP switch was used with a tape that was not the first tape of a set created 

by DSC. 

User Action: Change tapes and reenter the command line (see message 15). 
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1 7 Tape ddnn: not ANSI format 

Output Tape 

Explanation: If the medium is an output tape, the /AP switch was specified and the tape is 
not in ANSI format. 

User Action: Reenter the command line and either omit the /AP switch to write the specified 
tape or change to an ANSI tape. 

Input Tape 

Explanation: If the medium is an input tape, the tape is not in the correct format for a DSC 
operation (that is, the tape was not created by DSC). 

User Action: Check the tape and change it, if necessary. Reenter the command line. 

1 8 ddnn: not DSC tape 

Explanation: An /AP switch was specified with a tape that was not created by DSC. 

User Action: Reenter the command line and either omit the /AP switch or change to a 
DSC-created tape. 

19 Tape ddnn: a continuation tape 

Explanation: If the medium is an input tape, the tape was mounted out of sequence and is 
not the first of a set. 

User Action: Specify input tapes in the proper order and reenter the command line. 

2 1 Failed to And tiome block 

Explanation: DSC failed to find the home block on the input disk. The disk is bad, the 
home block is bad, or the disk is not in FUes-1 1 format. 

User Action: Check the disk in question; change drives, if possible; and reenter the command 
line. 

22 File Structure level on ddnn: not supported 

Explanation: The device is not a Files-1 1 disk, so it cannot be used. 
User Action: Replace the device and reenter the command line. 

23 I/O error A on ddnn: 

... (Additional error information) 

Explanation: The I/O error indicated explains why the index file bit map on the device 
could not be read. 

User Action: If possible, correct the cause of the error and reenter the command line. 
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24 I/O error B on ddnn: 

... (Additional error information) 

Explanation: The I/O error indicated explains why the index file header on the device could 
not be read. The specified file is lost. 

User Action: If possible, correct the cause of the error on the device and reenter the command 
line. 

25 Code A 

Explanation: The file header for the storage bit map file cannot be read. 

User Action: The disk is unusable and, therefore, cannot be copied. Replace the disk and 
reenter the command line. 

26 I/O error C on ddnn: 

... (Additional error information) 

Explanation: The I/O error indicated explains the error that occurred when DSC read the 
specified file. 

User Action: Reenter the command line. 

27 I/O error D on ddnn: 

... (Additional error information) 

Explanation: The I/O error indicated explains the read error that occurred when DSC read 
the home or boot block of the disk. 

User Action: Specify a new drive and reenter the command line. 

31 I/O error E on ddnn: File ID 
... (Additional error information) 

Explanation: The I/O error indicated explains why the specified file header could not be 
read. 

User Action: If possible, correct the cause of the error and reenter the command line. 

32 Input device ddnn; File ID, y, y. y not present 

Explanation: The specified file does not have a file header in the index file. The file is not 
copied. 

User Action: This is a warning only. If desired, the operation can be tried again on a 
different drive. 

33 Input device ddnn: File ID y, y, y is deleted 

Explanation: The specified file was partially deleted on the input disk and was not copied. 
User Action: This is a warning only. No user action is required. 
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34 Input device ddnn: File ID y, y, y unsupported structure level 

Explanation: The header of the file indicated by the message does not contain 000401 in its 
File Structure Level Field (indicates Files-11 Structure Level 1). DSC only copies Files-11 
Structure Level 1 files; therefore, this file wrill not be copied. 

User Action: This message is only a warning. DSC will attempt to copy the remainder of 
the input. 

35 Input device ddnn: File ID y, y, y die number check 

Explanation: An incorrect file header was read from the disk and caused the specified file to 
be lost. 

User Action: Reenter the command line. 

36 input device ddnn: File ID y. y, y file header checksum error 

Explanation: Incorrect file header contents caused the specified file to be lost. 
User Action: Reenter the command line. 

37 input device ddnn: File ID y, y, y sequence number check 

Explanation: The sequence number is incorrect. 

User Action: Replace the disk and reenter the command line. 

38 Input device ddnn: File ID y, y, y segment number check 

Explanation: The linkage connecting file segments was broken; the specified file is lost. 
User Action: Reenter the command line. 

39 Directive error - number 

Explanation: An internal error occurred, usually the result of a system overload. 
User Action: Reenter the command line. 

40 I/O error F on ddnn: 

... (Additional error Information) 

Explanation: The I/O error indicated explains that an uncorrectable read/write error occurred 
on the specified input or output device. 

User Action: This message is a warning only. No user action is required unless another 
error message is displayed. If another error message is displayed, correct the cause of the 
error and reenter the command line. 

41 I/O error I on ddnn: 
File ID y, y, y VBN z, z 

Explanation: An I/O error occurred that resulted in bad data being read from the specified 
virtual block number (VBN) of the indicated file on the indicated device. 

User Action: This is a warning message only. You should examine the block specified to 
determine the extent of the error. 
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42 Verification error on ddnn: 
File ID y, y, y VBN z, z 

Explanation: The input and output devices specified for a verification operation did not 
match. 

User Action: This is a warning message only. No user action is required. 

43 Bad data block on ddnn: 
File ID y. y, y VBN z, z 

Explanation: A parity error occurred when DSC copied the contents of a block from a disk. 
The block specified on the output disk contains erroneous data. 

User Action: When the copy operation is completed, the data contained in the specified 
block should be examined and corrected. 

44 Mount reel x on ddnn: and hit RETURN 

Explanation: This is an instruction only. 

User Action: Mount the volume number requested on the specified tape drive and press the 
RETURN key when ready. 

45 Starting verify pass 

Explanation: The copy operation is complete and DSC is beginning the verify operation 
(specified with the /VE switch). 

User Action: This is an informational message only. No user action is required. 

46 Resume copying 

Explanation: The verify operation (specified with the /VE switch) is complete and DSC is 
continuing the copy operation (if there is more material to copy). 

User Action: This is an informational message only. No user action is required. 

47 ddnn: is write locked. Insert write ring and hit RETURN. 

Explanation: The indicated device is write-locked. 

User Action: Make sure the device is the one you want, write-enable it, and press the 
RETURN key. Reenter the command line. 

48 Input file on ddnn: will be resynchronlzed 

Explanation: The tape position was lost while DSC was reading the input tape. The file 
specified in the message, as well as some subsequent files, may be lost. DSC may display 
additional error messages. 

User Action: Reenter the command line. 
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49 Output device ddnn: full 
File ID y, y. y 

Explanation: The spedfied device cannot accommodate the indicated contiguous file in a 
contiguous set of blocks. This may mean that there is an inconsistency in the input tapes. 

User Action: Specify a less fragmented output disk and reenter the command line. 

50 Output die header full on ddnn: x - File ID y, y. y 

Explanation: Too many bad blocks on the output disk have caused the generation of more 
retrieval pointers than can be stored in the current header or headers of the file. The 
allocation of blocks to the current output header is aborted. DSC will copy as many blocks 
as it has mapped to that header before it continues to allocate blocks to the header of the 
next output file. Note that some blocks will not be copied during this operation. 

User Action: After DSC completes the copy operation, use the Peripheral Interchange 
Program (PIP) to delete the unusable file on the output volume and to copy the file 
from the input volume to the output volume. 

PIP will assign a different file number to the output file, other than the original input file 
number, therefore the files will not compare when you use the /CMP switch. 

51 Output file header on ddnn: not mapped - File ID y, y, y 

Explanation: Space for the specified file header was not allocated. The file is lost. 
User Action: Reenter the command line; a new disk may be required. 

52 I/O error G on ddnn: 

... (Additional error information) 

Explanation: The I/O error indicated explains why the index file bit map could not be 
written. 

User Action: Reenter the command line. 

53 Failed to read file extension header on ddnn: - File ID y. y, y 

Explanation: When copying from the input disk, DSC searched for an extension header, but 
it did not find one. The remainder of the specified file was lost. A problem may exist with 
the input disk or a preceding I/O error may have caused an inconsistency. 

User Action: Reenter the command line. 

54 Failed to allocate home block 

Explanation: The home block cannot be created on the specified disk device because it has 
too many bad blocks. 

User Action: Replace the disk and reenter the command line. 

55 Index file allocation failure 

Explanation: Too many bad blocks exist to allow the allocation for the specified file. 
User Action: Replace the disk and reenter the command line. 
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56 Output disk ddnn: is not bootable 

Explanation: LBN 0, the bootstrap block, of the specified disk or tape is bad. (This message 
will always be preceded by message 84 and/or 86 indicating the reason for the error.) 

User Action: This is a warning only. No user action is required. 

57 Invalid bad block data 

Explanation: The bad block data on the output disk is invalid. 

User Action: Run the BAD program on the disk and manually enter bad block data or 
reenter the command line with another disk specified. 

58 Bod block file full 

Explanation: Too many bad blocks exist on the output disk. 
User Action: Replace the disk and reenter the command line. 

59 No bad block data found 

Explanation: No bad block data exists for the specified output disk. 

User Action: If bad block data is not desired, ignore the message. Otherwise, run the BAD 
program on the disk; manually enter bad block data; or reenter the command line with a 
new disk specified. 

60 Output device ddnn: is a diagnostic pack. Do not use it! 

Explanation: The specified output disk is a diagnostic pack and cannot be used. 
User Action: Mount a new output disk and reenter the command line. 

61 Code B on ddnn: 

File ID y, y, y - VBN z, z expected p,p,p found y 

Explanation: The tape position was lost when DSC read the virtual block number (VBN) 
specified. Some data may be lost. 

User Action: Detemune the extent of the error. If necessary, try the tape on another drive 
or create another tape. 

62 Code C ON ddnn: 
File ID y, y, y - VBN z, z 

Explanation: The tape position was lost when DSC read the data file specified. Data beyond 
the VBN mentioned was lost. 

User Action: Re-create the tape or reenter the command line with a different tape drive 
specified. 
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63 Code D on ddnn: 

File ID y, y, y expected p, p. p found y 

Explanation: The tape position was lost while DSC read the tape specified in the message. 
All of y, y, y" and some of "p, p, p" are lost. 

User Action: Reenter the command line. 

64 Failed to map output tile on ddnn: 
File ID y, y, y - VBN z, z 

Explanation: An inconsistency occurred when DSC was writing the specified file to output 
disk. The file header did not specify the correct number of virtual blocks required to write 
the file and the file is lost. 

User Action: Reenter the command line. 

65 Output disl( ddnn: Is too small — nn blocks needed 

Explanation: The output disk is not large enough to acconmiodate the data to be transferred. 
User Action: Specify a larger output disk and reenter the command line. 

66 i/O error C on ddnn: 

... (Additional error information) 

Explanation: The I/O error indicated explains why the storage bit map could not be read. 
User Action: Reenter the command line. 

67 I/O error H on ddnn: 

Explanation: The message that follows explains why the header of the storage bit map file 
could not be written. 

User Action: Reenter the command line. 

68 I/O error J on ddnn: 

... (Additional error Information) 

Explanation: The I/O error indicated explains why the tape labels on the specified device 
could not be read. 

User Action: Specify a different tape drive and reenter the command line. 

69 Input tape on ddnn: must be at EOT 

Explanation: The specified tape must be at beginrung-of-tape (BOT). This message is also 
displayed during a verify operation to indicate that the current volume is rewinding to 
enable the verify operation. 

User Action: If the /VE switch was not specified, check the tape and remount at BOT. 
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70 Wrong input tape on ddnn: 
Expecting File ID, found File ID 

Explanation: The input tapes were specified out of sequence. 

User Action: Check the tapes. Reenter them in proper order after you receive the mount 
instructions. 

71 Code E on ddnn: after File ID y, y, y 

Explanation: This message is the result of a read error from tape. When trying to read an 
attribute block, DSC accessed some other block. The file following the file specified in the 
error message is lost. 

User Action: Reenter the command line. 

72 I/O error K on ddnn: after File ID y, y, y 
... (Additional error information) 

Explanation: The I/O error indicated explains why the attributes of the specified file could 
not be read. 

User Action: Reenter the command line. 

73 I/O error L on ddnn: after File ID y, y, y 
... (Additional error information) 

Explanation: The message that follows explains the I/O error that occurred while DSC was 
reading the file header from tape. 

User Action: Reenter the command line. 

74 Input tape ddnn: resynchironized at File ID y, y, y 

Explanation: The tape position has been recovered. Some data preceding the file specified 
was lost. 

This message is usually received with one or more error messages, and it indicates that the 
input tape was either read incorrectly or was recorded badly. 

User Action: The tape should be re-created and the operation reinitiated. 

75 Tape file fileiabel not found 

Explanation: The input tape specified does not contain the file identified as "fileiabel." 

User Action: Check the file label and the tape, and then reenter the command line with the 
correct tape and file label specified. 

76 Expected extension header not present on ddnn: File ID y, y, y 

Explanation: A required file extension header could not be found on the tape being read. 

User Action: If the error message was preceded by one or more I/O warning messages, 
reenter the command line. If not, the input tape is bad and should be regenerated. 
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77 Code F on ddnn: after File ID y, y, y 

Explanation: This is the result of a read error from tape. When trying to read a file header, 
DSC accessed some other block type. The file following the file specified in the error 
message is lost. 

User Action: Reenter the command line. 

78 I/O error M on ddnn: 

... (Additional error information) 

Explanation: The message following the device name explains why the index file data could 
not be read. 

User Action: Reenter the command line. 

79 index file data not present 

Explanation: When reading the input tape, DSC accessed a file other than the index file. 
This message is the result of a tape error or an 1/0 error. 

User Action: Re-create the tape or retry the operation on a different tape drive. 

80 I/O error N on ddnn: 

... (Additional error information) 

Explanation: The 1/0 error indicated explains why the index and storage bit map files from 
the specified input tape could not be restored. 

User Action: Specify a different input tape drive and reenter the command line. 

81 Volume summary data not present 

Explanation: Either DSC did not create the input tape or the tape contains incomplete data. 
User Action: Check the tape and reenter the command line. 

82 I/O error O on ddnn: - File ID y, y, y 
... (additional error Information) 

Explanation: The I/O error indicated explains why the specified file header could not be 
written. 

User Action: Reenter the command line. 

83 Bad blocking factor 

Explanation: The specified blocking factor is too large for the current operating system. 
User Action: Specify a smaller blocking factor and reenter the command line. 

84 Input disk not bootable 

Explanation: The input disk does not have a valid boot block, therefore the output disk will 
not be bootable. This message will always be accompanied with message 56 that states that 
the output disk will not be bootable. 

User Action: This is a warning orJy. No user action is required. 
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85 Input/output disks differ 

Explanation: The boot block is usually different for each disk type, therefore the output disk 
may not have a valid boot block and may not be bootable. (This message will always be 
accompanied by other messages pertaining to the bootability of the output disk.) 

User Action: This is a warning only. If message 84 is also displayed, a copy from the output 
disk to another disk that is the same type as the original input disk will yield a disk that is 
bootable. 

86 Bad LBN # 

Explanation: The output disk has a bad LBN 0, which is the boot block; therefore, the output 
disk will not be bootable. 

User Action: This is a warning only. A copy from the output disk to another disk with a 
good LBN will yield a disk that is bootable. 

87 Output disk ddnn: may not be bootable 

Explanation: This message is always preceded by message 85, which indicates the reason 
for the error. Other messages concerning the bootability of the output disk may precede 
this message. (If message 56 is displayed, the output disk will not be bootable.) 

User Action: Refer to message 56 and messages 84, 85, and 86 for more details. 

6.8.2 DSC I/O Messages 

In DSC, I/O errors are prefixed by DSC — and are identified by one or more of the following 
messages, which explain the type of I/O error that occurred: 

Bad block number 

Explanation: The block does not exist on the disk; an internal DSC error has occurred. 
User Action: Reenter the command line. 

Bad block on device 

Explanation: A bad area was encountered on the device, which results in a block that cannot 
be read or written without error. 

User Action: Reenter the command line. 

Block check or CRC error 

Explanation: A parity error occurred, indicating that bad data may have been transferred. 
User Action: Reenter the command line. 

Data overrun 

Explanation: A physical block on tape contains more bytes than were requested. 
User Action: Reenter the command line. 



6-34 Disk Save and Compress Utility (DSC) 



Device not ready 

Explanation: The device is not ready or is not up to speed. 
User Action: Reenter the command line. 

Device offline 

Explanation: The device is not in the system. 

User Action: Check the device and the device specification in the command line, and then 
reenter the command line. 

Device write loclced 

Explanation: The disk drive is write-locked. 

User Action: Write-enable the disk drive and reenter the command line. 

End of file detected 

Explanation: The tape position was lost. 
User Action: Reenter the command line. 

End of tape detected 

Explanation: The tape position was lost. 
User Action: Reenter the command line. 

End of voiume detected 

Explanation: The tape position was lost. 
User Action: Reenter the command line. 

Fatal hardware error 

Explanation: A hardware malfunction occurred. 

User Action: Reenter the command line. If the error repeats, call your DIGITAL Field Service 
representative. 

Handier not resident 

Explanation: The device driver (handler) was not loaded. 

User Action: Load the appropriate device driver and reenter the command line. 

insufficient pool space 

Explanation: The operating system is overloaded. 
User Action: Reenter the command line. 

Parity error on device 

Explanation: An uncorrectable read error occurred. 
User Action: Reenter the command line. 
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Privilege vioiation 

Explanation: A device was mounted as Files-11 or is allocated to a different user. 

User Action: Dismount the disk, mount it as a foreign device, and reenter the command 
line. 

Error code is <clriver code> 

Explanation: An I/O error that DSC cannot translate occurred. 

User Action: If possible, translate the error code and reenter the command line. 

lilegal function 

Explanation: Tapes on drives have not been rewound since the system was booted. 
User Action: Rewind the tapes by using the /RW switch in a DSC command line. 
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Chapter 7 

Line Text Editor (EDI) 



EDI is a line-oriented editor that allows you to create and modify text files. EDI operates on 
most American Standard Code for Information Interchange (ASCII) text files. It is frequently 
used to create and maintain FORTRAN or MACRO- 11 source files. 

EDI accepts over 50 commands that determine its mode of operation and control its actions on 
input files, output files, and working text buffers. The commands fall into the following eight 
categories: 

Basic commands Allow you to create, modify, and exit files. 

Setup commands Select operating conditions, close and open files, and select 

data modes. 

Locator commands Control the position of the current line pointer and thus 

determine which text line is acted upon. 

Text modification commands Change text lines. 

Macro commands Use, store, recall, and define sequences of EDI commands. 

File input and output commands Transfer text to and from input, output, and saved files. 

Device output commands Send output to a terminal or a printer. 

Close and exit commands Terminate editing operations. 

Commands are categorized in this chapter as EDI Commands: Function Summary (Section 1.7) 
and EDI Commands: Detailed Reference Summary (Section 7.8). Restrictions, system device 
considerations, and error messages for the commands are discussed in Section 7.9 and 
Sections 7.11 to 7.11.4. 
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7.1 EDI Command Line 

You can invoke EDI by using any of the methods described in Chapter 1. The command line 
for EDI is shown next. 

Format 

filespec 

Parameter 

filespec 

Specifies a file specification in the following format. 

ddnn: [directorylfilename. type; version 

Refer to Chapter 1 for detailed descriptions of the parameters for file specifications. 

The abbreviation "filespec" is used throughout this chapter to denote a file specification that you 
supply. 

If the file specification is a new file (that is, the file specified cannot be found on the specified 
device), EDI assumes that you wish to create a new file with the given file name. EDI then 
prints the following: 

[CREATING NEW FILE] 
input 

EDI then enters input mode. (EDI control modes are described in Section 7.2.) 

If the message [FILE DOES NOT EXIST] is printed, it means that the directory corresponding 
to the User Identification Code (UIC) is nonexistent. 

EDI does not accept indirect command file specifications. 

If you specify an existing file name, EDI prints the following: 

[OOOnn LINES READ IN] 
[PAGE 0] 

* 

It then waits in edit mode for you to issue the first command. 

If the "> EDI filespec" format is used, the prompt (EDI> ) is not issued, and EDI starts up in 
either input or edit mode, depending on the file name specified — input mode if the file name 
is new, edit mode if the file name already exists. 

After EDI has identified the input file and created the output file, it is ready for commands. In 
edit mode, the first line available for editing is one line above the first line of the input file or 
the block buffer. Therefore, you can insert text at the beginning of the input file or the block 
buffer by issuing the Insert command. To manipulate the first line of text, on the other hand, 
you must issue the Next command to make that line available. 
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7.1.1 Defaults in File Specifications 

EDI uses a default if any of the elements of the file spedfication, except the input file name, is 
omitted. In general, EDI processing creates an output file. When you are modifying an existing 
file, EDI uses that file and your modifications to create an output file. When the editing session 
is complete, the output file usually has the same file spedfication as the input file, except the 
file system renumbers the version to one greater than the previous version. The default values 
for input and output files are hsted in Table 7-1. 

Table 7-1: EDI Default File Specifications 



Element 



Default Value 
for Input File 



Default Value 
for Output File 



ddnn SYO 

directory Directory under which EDI 

is ciurently running 

filename No default — must be sped- 

fied 

type Unspecified 

version Latest version 



Same as input device 
Same as input directory 

Same as input file name 

Same as input file type 
Latest version + 1 



7.2 EDI Control Modes: Edit and Input 

EDI runs in two control modes: 

• Edit (command) mode 

• Input (text) mode 

Edit mode is invoked automatically when you spedfy an existing file. 

In edit mode, EDI issues an asterisk (*) prompt. EDI acts upon commands and data to open 
and close files; to bring lines of text from an open file; to change, delete, or replace information 
in an open file; or to insert single or multiple lines anywhere in a file. 

Input mode is invoked automatically at program startup if you specify a nonexistent file. 

When in input mode, EDI does not issue an explidt prompt. Lines that you enter at the terminal 
are treated as text and are inserted into the output file. When you complete each input line by 
pressing the RETURN key, EDI sends a line feed to the terminal. 

To switch from edit mode to input mode, enter the Insert command and press the RETURN key. 
To return to edit mode, press the RETURN key as the only character on an input line. EDI will 
issue the asterisk ( • ) prompt, which signifies edit mode. 
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7.3 Text Access Modes 

EDI provides two modes you can use to access and manipulate lines of text in the input file. 
(A line is defined as a string of characters terminated by pressing the RETURN key.) The two 
modes are as follows: 

Line-by-line mode Allows access to one line of text at a time. Backing up is not allowed. 

Block mode Allows free access within a block of lines, on a line-by-line basis. Backing 

up within a block is allowed. Backing up to previous blocks is not allowed. 

Block mode is the default text access mode. In addition to these two text access modes, EDI 
provides a way to process text "pages." 

7.3.1 Line-by-Une Mode 

In this mode, a single line is the unit of the input file available for modification. Line-by-line 
mode is entered by issuing the Block Off command and is terminated by issuing the Block On 
command. 

The single available line — the current line — is specified by a pointer, which you can move 
sequentially through the file, starting just before the first line in the file. You can manipulate 
the line pointer by using the locator commands and the text modification and manipulation 
commands discussed later in this chapter. However, you cannot easily direct the pointer 
backward within the file. 

When you open a file at the beginning of an editing session, you can specify that the first line 
be brought into memory and made available for modification. This line remains in memory 
until you request that a new line be brought in. The pointer then moves down the file until the 
line you requested is encountered. That line is brought into memory and, as the current line, 
can be modified. When a new line is brought in, the previous line is vratten into the output 
file, as are all lines that may be passed over in reaching the new current line. 

Once the pointer moves past a line, that line is no longer accessible unless you enter the Top 
or Top of File command (refer to Sections 7.8.53 and 7.8.54). Top of File causes the input and 
output files to be closed and the output file to become the new input file. Top of File also ends 
line-by-line mode. 

7.3.2 Block Mode 

In this mode, a portion of the input file is held in a buffer for editing until you request that the 
contents of the buffer be added to the output file. 

In block mode, you can access lines of text backward as well as forward within the buffer. 
Thus, you can back up to a previously edited line without having to reprocess the entire block 
or file and without having to issue the Top of File command. 

When you finish editing a block, you can write it out and read in the next block with the Renew 
command. However, you cannot access a previously edited block except by using the Top of 
File command. 
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EDI buffer space is computed dynamically at run time. The number of lines initially read into 
the buffer is computed by using the following formula: 

buffersize/132 

A block is the number of lines read into the buffer by the Renew or Read command. This 
number is one of the following: 

• Specified with the Size command (default is 38 lines if the Size command is not issued) 

• Determined by the presence of a form feed at a point in the text where the number of lines 
is less than that specified in the Size command (or its default value, if the Size command 
was not issued) 

When the current line pointer reaches the end-of-block, the message [*EOB*] is displayed and 
the current line pointer points to the last line in the block. To move the current line pointer to 
the top of the block, use the Top command. 

Table 7-2 briefly summarizes the differences between line-by-line and block mode. Regardless 
of the editing mode, the line pointer always points to the first character in the line. 

Table 7-2: Line-by-Line and Block Mode Differences 



Line-by-Line Mode Block Mode 



One line is available for modifi- A block of lines is available for modification at a time, on a 
cation at a time. line-by-line basis. 

Lines can only be accessed Lines can be accessed forwards and backwards within a block, 

forward through the file. 

Search commands can search Search commands can search only the block in memory. To 
the entire file. search more data, you must read in another block. 

7.3.2.1 Processing Text In Pages 

EDI provides features that allow you to access portions of a text file by page. A "page" is a 
segment of text delimited by form-feed characters (the last page in a file is terminated by the 
end-of-file (EOF) marker). 

Two commands are provided to handle paged text: the Form Feed command, which defines a 
page boundary by inserting a form feed, and the Page command, which accesses a page of text. 
(The commands Page Find and Page Locate do not refer to form-feed-delimited pages — they 
are actually global searches.) 

EDI handles paged text in block mode. If block mode is not already in effect, it is entered when 
you issue the Page command. 

If a form feed is encountered in text during a Read or Renew operation, the page, thus delimited 
for purposes of the Read or Renew command, is interpreted as a block. 

The message [PAGE n], issued after a Read or Renew operation, gives the value of EDI's page 
counter. If your text contains no form-feed characters, the count is zero until the last block in 
the file is read into the buffer. Upon encountering the EOF, EDI increments the page count 
to 1. 
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7.4 Text Files 

The following sections describe how data may be added to files and the operations performed 
on output files. 

7.4.1 Input and Secondary Files 

EDI accepts input from the following: 

• The input terminal (that is, commands and text entries) 

• Files-1 1 volumes that contain any of the following: 

— The file to be edited 

— A secondary file 

— A save file 

— A macro file 

The input file is always preserved.^ Any system failure, EDI failure, or lack of space on the 
output volume does not cause the loss of the input file. Only the output file is affected. In 
cases of failure, the output file is not completely destroyed. Instead, it becomes a truncated 
version of the input file containing all of the edits to the point of failure. 

In general, the current block buffer is not written to disk when an error of this type occurs. 

7.4.2 Output Files 

The output file defaults to the input file device, directory, file name, and file type specifications. 
The version number is incremented by one. 

If you wish to change any of these parameters (except device and directory), specify a new file 
specification when closing a file or exiting at the end of an EDI session. 

7.5 Terminal Conventions 

RSX-llM-PLUS and EDI provide terminal keyboard functions that allow you to perform the 
following tasks: 

• Delete characters on an input line. 

• Delete an entire input line. 

• Move the current line pointer forward in a file. 

• Move the current line pointer backward in a file. 

• Terminate an editing session and return control to your command line interpreter (CLI) (for 
example, the Monitor Console Routine (MCR) or DIGITAL Command Language (DCL)). 



^ To delete the input file, use the Close & Delete command or the Exit & Delete command, or use PIP (see Chapter 12). 
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7.5.1 Character Erase— DELETE or RUBOUT; CTRL/R 

Pressing the DELETE key (marked RUBOUT on some terminals) deletes individual characters if 
used before the RETURN key is pressed. During editing operations, pressing the DELETE key 
does not affect previously prepared text. 

When you press the DELETE key, it is echoed as a backslash (\) followed by the previously 
typed character. Pressing each successive DELETE key results in the echo of an earlier typed 
character. When you type the first new character, it is echoed as a backslash (closing the DELETE 
key sequence) followed by the typed character. For example: 

First DELETE pressed MISTKAE\E 

Second DELETE MISTKAE\EA 

Third DELETE MISTKAE\EAK 

First non-DELETE MISTKAE\EAK\AKE 

For some video terminals, the DELETE key works in a more obvious way. Pressing the DELETE 
key causes the cursor to backspace, erasing the previous character. Your video terminal may 
work this way if a certain option was selected when your system was generated. 

Another useful system generation option is CTRL/R. It is entered by pressing the CTRL key 
while simultaneously pressing the R key. On some terminals, pressing CTRL/R echoes as ''R. 
Your system responds to your pressing CTRL/R by printing the incomplete input line followed 
by a return and line feed. For example, at a hardcopy terminal you enter: 

MISTKAE [DEL] [D|L] [DfU] I CTRL/R | 

The echoed result is: 

mSTKAE\EAK-R 
MIST 

7.5.2 Line Erase— CTRL/U 

Pressing CTRL/U deletes the line being input, if typed before the line is terminated with the 
RETURN key. It is entered by pressing the CTRL key and the U key simultaneously. On some 
terminals, pressing CTRL/U echoes as "U and is followed by a return and line feed. 

7.5.3 RETURN Key 

The RETURN key has the following effects, depending on how it is used: 

• When issued in place of an input file specification, pressing the RETURN key causes EDI to 
terminate. 

• When issued in edit mode, pressing the RETURN key causes the next line to be printed. 
That line becomes the current line. 

• When issued in input mode as the only character in an input line, pressing the RETURN key 
causes a return to edit mode. 

• When issued alone after an Insert command, pressing the RETURN key invokes input mode. 
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7.5.4 Terminating the Previous Text Line — ESCAPE or ALTIVIODE 

When EDI is in edit mode, pressing the ESCAPE (or ALTMODE) key causes the previous text 
line to be printed. That line becomes the current line. ESCAPE can be used this way only in 
block mode, not in line-by-line mode. 

When EDI is in input mode, pressing the ESCAPE key produces the same results as pressing 
the RETURN key: it terminates the line. If ESCAPE is the first character of an input line, EDI 
exits from input mode. 

7.5.5 Terminating EDI — CTRL/Z 

Pressing CTRL/Z causes EDI to terminate. EDI writes the remainder of the input file into the 
output file and then closes both files before terminating. Press CTRL/Z to terminate EDI in edit 
mode and input mode. Pressing CTRL/Z erases your last input line if you enter the command 
as a line terminator. 

7.6 EDI Command Conventions 

EDI uses asterisks (*) and ellipses (...) in special ways. The following sections describe these 
and also the notation convention used to define EDI command abbreviations. 

7.6.1 Use of Asterisk 

The asterisk (*) can be used in place of any numeric argument. It evaluates to 32,767io. 

Example 

p * [retI 

Prints the remainder of the block buffer or file. 

7.6.2 Use of Ellipsis In Search) Strings 

In a number of the EDI commands, you must identify a string of characters to be located 
and/or changed. To reduce the necessary terminal entries, you can use the following special 
string constructs. In these special cases, the ellipsis (...) represents any number of intervening 
characters. 

Case 1 

string 1...string2 

Indicates any string that starts with stringl, continues with any number of intervening 
characters, and ends vdth the first occurrence of string2. 

Case 2 

...string 

Indicates any string that starts at the beginning of the current line and ends with the first 
occurrence of string. 



7-8 Line Text Editor (EDI) 



Case 3 

string... 

Indicates the first string that starts with string and ends at the end of the current line. 

Case 4 

Indicates the entire current line. 

Examples 

In the following examples, the Change comniand is used with the four cases of special string 
constructs. In each case, the current line reads as follows: 

THIS IS A SAMPLE OF SPECIAL STRING CONSTRUCTS. 
Case 1 

*C /S A. . .E 0/S AN EXAMPLE [Ml 

Results in the following: 

THIS IS AN EXAMPLE OF SPECIAL STRING CONSTRUCTS. 

Case 2 

*C /...SPEC/HERE IS AN EXAMPLE OF SPEC [Ml 

Results in the following: 

HERE IS AN EXAMPLE OF SPECIAL STRING CONSTRUCTS. 

Case 3 

*C /STRING... /EDI STRING CONSTRUCTS. [M 

Results in the following: 

HERE IS A SAMPLE OF SPECIAL EDI STRING CONSTRUCTS. 

Case 4 

*C /.../EXAMPLES OF SPECIAL EDI CONSTRUCTS. [Ml 

Results in the following: 

EXAMPLES OF SPECIAL EDI CONSTRUCTS. 
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7.6.3 Command Abbreviations 

EDI pennits the use of truncated commands. Where these shorter forms are allowed, the 
command format specifications represent the shortest acceptable form in uppercase letters. The 
command format specification for the Verify command is as follows: 

V 

However, the following truncations are valid for the Verify command: 

V 

VE 

VER 

VERI 

VERIF 

VERIFY 

7.7 EDI Commands: Function Summary 

EDI commands can be arranged by functional similarity. For example, all the commands you 
use to locate a string can be grouped under the function heading "Locator Commands.' The 
following sections contain summaries of the command categories. 

7.7.1 Basic Commands 

The basic EDI commands listed in Table 7-3 allow you to create a file; to modify a file by 
adding, deleting, or changing its contents; and to exit a file after the desired operations have 
been completed. Basic commands are the most important EDI commands. 



Table 7-3: Basic EDI Commands 



Command 



Format 



Function 



Add 

Add & Print 



A string 
AP string 



ALTMODE key Press the ALTMODE key 



Bottom 



Change 



BO 



[n]C /stringl/shing2[/] 



Press CTRL/Z 


D[n] 
D-n 



Appends string to current line. 

Appends string to current line and prints resulting 
line. 

Prints previous line, makes it the new current line 
and exits from input mode (block mode only). 
Same as NP-1. 

Moves the aurent line pointer to the bottom of 
the current block (in block mode) or to the bottom 
of the file (in line-by-line mode). 

Replaces stringl with string2 n times in the 
current line. 

Closes files and terminates editing session. 

Deletes current line and n-1 lines if n is positive; 
deletes n lines preceding the current line if n is 
negative (-n). Operates in block mode only. 
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Table 7-3 (Cent.): Basic EDI Commands 



Command 



Format 



Function 



Top of File 



Type 



Delete & Print 


DP[n] 
DP -n 


ESCAPE key 


Press the ES 


Exit 


EX [filespec] 


Insert 


I [string] 


Locate 


[n]L [string] 


Next 


N[n] 
Next -n 


Next & Print 


NP [n] 
NP -n 


Print 


P[n] 


Renew 


REN [n] 


RETURN key 


Press the RE 


Retype 


R [string] 


Top 


T 



TOF 



TY[n] 



Same as the Delete command, except new current 
line is printed. 

Prints previous line, makes it the new current line, 
and exits from input mode (block mode only). 
Same as NP-1. 

Closes files, renames output file, and terminates 
editing session. 

Enters the string immediately following the cur- 
rent line. If no string is specified, EDI enters 
input mode. 

Locates nth occurrence of string. In block mode, 
search stops at end of current block. 

Establishes new current line n lines away from 
current line. 

Establishes and prints new current line. 



Prints current line and the next n-1 lines. The 
last printed line is the new current line. 

Writes current block to output file and reads new 
block n from input file (block mode only). 

Prints the next line, makes it new current line, 
and exits from input mode. Same as NP+1. 

Replaces current line with string or deletes current 
line if string is not given. 

Moves the current line pointer to the top of the 
current block (in block mode) or top of file (in 
line-by-line mode). The Top command creates a 
new version of the file each time it is invoked in 
line-by-line mode. 

Returns line pointer to top of input file and saves 
all pages previously edited. TOF creates a new 
version of the file each time it is invoked. TOF 
reads in a new block after writing the previous 
block to the output file. 



Prints current line and the next n-1 lines, 
last printed line is the new current line. 



The 
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7.7.2 Setup Commands 

The setup commands allow you to enable or disable certain special features of EDI. Among 
these features are the block and line-by-line text access modes, and the automatic verification 
of Locate and Change commands. Setup commands are listed in Table 7-4. 

Table 7-4: EDI Setup Commands 



Command 



Format 



Function 



Block On/Off 


BL [ON] 
BLOFF 


Concatenation 


CC [character] 


Character 




Open Secondary 


OP filespec 


Output On/Off 


OU [ON] 
OUOFF 


Select Primary 


SP 


Select Secondary 


SS 


Size 


SIZE n 


Tab On/Off 


TA [ON] 
TAOFF 


Uppercase On/Off 


UC [ON] 
UC OFF 


Verify On/Off 


V[ON] 
VOFF 



Switches text access modes. 

Changes concatenation character to specified character 
(default is the ampersand ( & )). 

Opens specified secondary file. 

Continues or discontinues transfer to output file (line- 
by-line mode). 

Reestablishes primary file as input file. 

Selects opened secondary file as input file. 

Specifies maximum number of lines to be read into 
block buffer. 

Turns automatic tabbing on or off. 

Enables or disables conversion of lowercase letters 
entered from terminal to uppercase letters. 

Selects whether locator and change commands are 
verified. 



7.7.3 Locator Commands — Line-Pointer Controi 

During editing operations, EDI maintains a pointer that identifies the current line (that is, the 
line to which any subsequent editing operations refer). Commands that modify the line pointer's 
location are called locator commands. These commands are listed in Table 7-5. 

The locator commands allow you to perform the following tasks: 

• Set the line pointer to either the top or bottom of the input file or block buffer. 

• Move the line pointer a specified number of lines away from its current position. 

• Move the line pointer to a line containing a given text string. 

In edit mode, pressing the RETURN, ESCAPE, or ALTMODE key acts to relocate the line pointer. 
Pressing the RETURN key moves the pointer to the next line. Pressing the ESCAPE or ALTMODE 
key moves the line pointer back one line (in block mode only). In each case, the line is printed. 
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If the Verify On command is in effect, the located line is printed after the Bottom, End, Find, 
Page Find, Page Locate, or Search & Change command. 

Table 7-5: EDI Locator Commands 



Command 



Format 



Function 



ALTMODE key Press the ALTMODE key 



Begin 
Top 



Bottom 
End 

ESCAPE key 
Find 

Locate 

Next 

Next & Print 

Page 

Page Find 
Page Locate 



B 
T 



BO 

E 



Press the ESCAPE key 



[n]F [string] 



[n]L [string] 



N[n] 
N -n 

NP [n] 
NP -n 

PAGn 



[n]PFind string 



[n]PL string 



RETURN key Press the RETURN key 



Prints previous line, makes it new current line, 
or exits from input mode (block mode only). 

Sets current line to the line preceding top line 
in file (line-by-line mode) or block buffer (block 
mode). Both commands create copies of the file 
each time they are invoked in line-by-line mode. 
The commands are equivalent. 

Sets current line to last line in file or block buffer. 
The commands are equivalent. 

Prints previous line, makes it new current line, 
or exits from input mode (block mode only). 

Searches current block or input file, beginning at 
line following current line for the nth occurrence 
of string. String must begin in column 1. Sets 
line pointer to located line. 

Locates nth occurrence of string. In block mode, 
search stops at end-of-block. 

Establishes new current line n lines away from 
current line. 

Establishes and prints new current line. 



Enters block mode. Reads page n into block 
buffer. If n is less than current page number, 
issue a TOF command first (block mode only). 
Pages are delimited by formfeed characters. 

Searches successive blocks for the nth occurrence 
of string (block mode ordy). String must start in 
column 1. 

Searches successive blocks for the nth occurrence 
of string (block mode only). String may occur 
an5fwhere in line. 

Prints the next line, makes it the current line, 
exits from input mode. 



Search & Change SC /stringl/string2[/] Locates stringl and replaces it with string2. 
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7.7.4 Text Modification and IVIanipuiation Commands 

The text modification and manipulation commands enable you to modify text. Table 7-6 lists 
these commands. 



Table 7-6: EDI Text Modification and Manipulation Commands 



Command 



Format 



Function 



Add 

Add & Print 

Change 



A string 
AP string 

[n]C /stringl/string2[/] 



Delete 


D[n] 
D -n 


Delete & Print 


DP[n] 
DP-n 


Erase 


ERASE [n] 


Form Feed 


FF 


Insert 


I [string] 


Line Change 


[n]LC /stringl 


Overlay 


0[n] 


Paste 


PA /stringl/sl 


Retype 


R [string] 


Top of File 


TOP 


Unsave 


UNS [filespec] 



Appends string to current line. 

Appends string to the current line and prints 
resulting line. 

Replaces stringl with string2 in the current line 
n times. 

Deletes current line and n-1 lines if n is 
positive; deletes n lines preceding current line 
if n is negative (-n operates in block mode 
only). 

Same as the Delete command except new 
current line is printed. 

Erases the current line if in line-by-line mode. 
Erases the current block buffer and the next n-1 
blocks if in block mode. 

Inserts form feed into block buffer (used to 
delimit a page). 

Enters string following current line or enters 
input mode if string is not specified. 

Changes all occurrences of stringl in current 
line (and n-1 lines) to string2. 

Deletes n lines, enters input mode, and inserts 
new line or lines as typed in place of original 
line or lines. 

Searches all remaining lines in file or block 
buffer for stringl and replaces with string2. 

Replaces the current line with string or deletes 
the current line if string is not given. 

Returns to the top of the input file and saves 
all pages previously edited. 

Inserts all lines from specified file following 
current line. If filespec is not given, SAVE.TMP 
is used. 
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7.7.5 Macro Commands 

The Macro commands allow you to define, store, recall, and use macros. A macro is a series 
of EDI commands that, once defined, can be executed repeatedly. Table 7-1 lists the macro 
commands. 



Table 7-7: EDI Macro Commands 



Command 



Format 



Function 



MACRO X defini- Defines macro number x. The value x may be 
1, 2, or 3. 

Retrieves macro definitions stored in file 
MCALL;n. 

Executes macro x [n] times, while passing nu- 
meric argument [a]. 

[n] < definition > Defines and executes a macro n times. Stores it 
as macro number 1. 



Macro 


MACRO 




tion 


Macro Call 


MC 


Macro Execute 


[n]Mx [a] 


Macro Immediate 


fnl <def 



7.7.6 File Input and Output Commands 

The input and output commands control the movement of text to and from input and output 
files, and they save files. Table 7-8 lists these commands. 



Table 7-8: EDI Input/Output Commands 



Command 



Format 



Function 



File 



Write 



FIL filespec 



Read 


REA [n] 


Renew 


REN [n] 


Save 


SA [n] [filespec] 



w 



Transfers lines from input file to both the output file and 
the specified file until a form feed or end-of-file (EOF) is 
encountered (line-by-line mode only). 

Reads next n blocks of text into block buffer. If buffer 
contains text, new text is appended to it. 

Writes the current block to the output file and reads new 
block from the input file. 

Saves current line and the next n-1 lines in the specified 
file. If filespec is not given, lines are saved in file 
SAVE.TMP. The Save command puts the temporary file 
in the directory on the device for the file you are editing. 
You can override the default by specifying a different 
device and directory. 

Writes contents of block buffer to output file and erases 
block buffer. 
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7.7.7 Device Output Commands 

The device output commands direct output to your terminal or to a pseudo device (CL). They 
are listed in Table 7-9. 



Table 7-9: EDI Device Output Commands 



Command 



Format 



Function 



List on Pseudo Device LP 



List on Terminal 


LI 


Print 


P[n] 


Type 


TY[n] 



Same as the List on Terminal command, except that 
printing is performed on the pseudo device CL. 

Prints on the terminal all lines remaining in block 
buffer (block mode) or input file (line-by-line mode), 
beginning at current line. 

Prints the current line and the next n-1 lines. The last 
printed line is the new current line. 

Prints next n lines. In line-by-line mode, it is 
identical to the Print command. In block mode, line 
pointer remains at current line unless end-of-block was 
reached. 



7.7.8 Close and Exit Commands 

Close and exit commands terminate EDI operations and write the remainder of the input file 
into output file. Table 7-10 lists these commands. 



Table 7-10: EDI Close Operation Commands 



Command 



Format 



Function 



Close 



Kill 



CL [filespec] 



Close Secondary 


CLOSES 


Close & Delete 


CD [filespec] 


CTRL/Z 


Press CTRL/Z 


Exit 


EX [filespec] 


Exit & Delete 


ED [filespec] 



KILL 



Transfers remaining lines in block buffer and input 
file to output file and closes files. If file specification 
is used, output file is renamed. EDI> prompt is 
issued. 

Closes secondary file. 

Same as Close except that input file is deleted. 
EDI> prompt is issued. 

Closes files and terminates EDI. 

Closes files, renames output file, and terminates EDI. 

Transfers remaining lines in block buffer and input 
file to output file and doses file. Renames file if 
file specification is given. Deletes input file and 
terminates EDI. 

Closes input and output files, and deletes output 
file. The EDI> prompt is issued. 
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7.8 EDI Commands: Detailed Reference Summary 

This section lists each EDI command in alphabetical order. Each command description comprises 
the function of the command, the command format, usage information, and examples. 

7.8.1 Add 

The Add command causes the specified string to be appended to the current line. 

Format 

A string 

Example 

*A AGAIN. [RfT] 

Completes the line HAPPY DAYS ARE HERE. 

Note that the space after the A is the command terminator. EDI will not insert the space into 
the line. If a space is to precede AGAIN., the command should include the space as part of the 
string, as follows: 

*A AGAIN. [RET] 

7.8.2 Add & Print 

The Add & Print command performs the same function as the Add command except that the 
new line is printed. 

Format 

AP string 

Example 

*AP AGAIN. [REtI 

HAPPY DAYS ARE HERE AGAIN. 

Adds the string and prints the new line. 

7.8.3 ALTMODE Key 

Pressing the ALTMODE key causes the system to print the previous line in the block (block 
mode only). That line becomes the current line. Thus, you can back up through a block, one 
line at a time, by pressing a series of ALTMODE keys. Pressing the ALTMODE key is equivalent 
to typing NP-1 (Next & Print command) or pressing the ESCAPE key. 

If EDI is in input mode, the ALTMODE key acts like the RETURN key and terminates a line of 
input. Pressing the ALTMODE key also exits EDI from input mode if it is the first character of 
the line. 
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7.8.4 Begin 

The Begin command sets the current line pointer to the beginning of the file in line-by-line 
mode or to the beginning of the block buffer in block mode. The current line is one line 
preceding the top line in the file or block buffer. Thus, you can insert text at the beginning of 
a file or block. 

If EDI is in line-by-line mode. Begin copies the input file into the output file, closes both, and 
then opens the latest version of the file. The Begin command performs the same function as 
the Top command. 

Format 
B 

Example 

Moves the current line pointer to the top of the block buffer (block mode is assumed). 

7.8.5 Block On/Off 

The Block On/Off command allows you to switch between block mode and line-by-line mode. 
When you enter the Block On command, block mode becomes active and the next block of text 
is brought into the block buffer. When you enter the Block Off command, the current block 
being processed is written to the output file and line-by-line mode becomes active. The first 
line from the next sequential block in the input file becomes the current line. 

If you enter an unnecessary Block command (for example, entering the Block On command 
when EDI is already in block mode), the command is ignored. 

The Block On command is the default text access mode. It is assumed when neither ON nor 
OFF is specified. 

Format 

BL [ON] 

or 

BLOFF 

Example 

*BL ON dm 

Switches EDI to block mode. The next block of text is read into the block buffer. 
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7.8.6 Bottom 

The Bottom command moves the current line pointer to the beginning of the last line of the 
current block (in block mode) or to the beginning of the last line of the fQe (in line-by-line 
mode). In block mode, the only processing EDI performs is line pointer positioning. In line-by- 
line mode, all the lines are copied from the input file to the output file until EOF is reached. If 
the Verify On command is issued, the last line of the file block is displayed. Note, however, 
that if you deleted the last line before you issued the Bottom command, the line pointer will be 
located past the text, and thus the last line will not be printed. The Bottom command performs 
the same function as the End command (see Section 7.8.15). 

Format 
BO 

Example 



*V ON [RET] 

*B0 [BH] 

THIS IS THE LAST LINE 

Moves the current line pointer to the bottom of the block buffer and prints the last line. 

7.8.7 Cticnge 

The Change command searches for stringl in the current line and, if found, replaces it with 
string2. If stringl is given, but cannot be located in the current line, EDI prints [NO MATCH] 
and returns an asterisk ( * ) prompt. If stringl is not given, string2 is inserted at the beginning 
of the line. If string2 is not given, stringl is deleted from the current line. 

The search for stringl begins at the beginning of the current line and proceeds across the line 
until a match is found. 

The characters that delimit stringl and string2 are normally slashes ( / ). However, any matching 
characters not contained in the specified string may be used. The first character following the 
command is the beginning delimiter; the next matching character ends the string. Thus, 
characters used as delimiters must not appear in the string itself. The closing delimiter is 
optional. 

If you precede the command with a number n, the first n occurrences of stringl are changed to 
string2. After each replacement of stringl with string2, scanning restarts at the first character 
in the line. This allows you to generate a string of characters as shown in the example. 

If no match occurs, a [NO MATCH] message is displayed. 
Format 

[n]C /stringl /string2[/] 
Example 

TO SEPERATE THE THOUGHTS, USE SEPERATE SENTENCES. 

*2C /SEPE/SEPA/ [Ml 

TO SEPARATE THE THOUGHTS, USE SEPARATE SENTENCES. 

Changes the string SEPE to the string SEPA. 
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7.8.8 Close 

The Close command transfers all remaining lines in the block buffer and input file (in that 
order) into the output file and closes both files. If a file specification is included, the output 
file is renamed to the filespec. EDI then returns to its initial command sequence, prompts with 
ED1> , and waits for you to type another file specification. 

If a secondary file was opened during the editing session and was not closed, it remains open. 

Format 

CL [filespec] 

Example 



*CL [RET] 
EDI> 

Closes both input and output files; then, returns to the initial command sequence. 

7.8.9 Close Secondary 

Use the Close Secondary command when you have finished extracting text from a secondary 
input file. You must enter the Close Secondary command before you can use another secondary 
file as input. 

Format 

CLOSES 

7.8.10 Close & Delete 

The Close & Delete command transfers all remaining lines in the block buffer and the input file 
(in that order) into the output file, and it closes both files. The input file is then deleted. If a 
file specification is included, the output file is renamed to the filespec. This command acts like 
the Close command except that the input file is deleted. 

If a secondary file was opened during the editing session and was not closed, it remains open. 

Format 

CD [filespec] 

7.8.11 Concatenation Character 

The concatenation character allows you to give commands on one input line. By default, the 
concatenation character is the ampersand (&). To reference text contairung an ampersand (for 
example, in the Locate or Change command), you must change the concatenation character to 
some other character. 

If the Concatenation Character command is used without an argument, the concatenation 
character is the ampersand. 

Format 

CC [character] 
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Example 

*CC : [RETI 

*L AftB:C /AfcB/ABC/ \M] 
CONCATENATION TEST CONTAINING AftB. 
CONCATENATION TEST CONTAINING ABC. 
*CC fRET] 



In the previous command lines, the string to be located contains an ampersand. Therefore, the 
concatenation character must be changed to a different character before EDI can locate the line. 

The first command line changes the default concatenation character from the ampersand to the 
colon (:). 

The second command line instructs EDI to locate the string A&B and change that string to 
ABC. (Note: this line contains two commands that are concatenated by the new concatenation 
character, the colon.) 

The third command line changes the concatenation character back to the normal default value: 
the ampersand. 

7.8.12 CTRL/Z 

CTRL/Z is a CLI function that terminates EDI. Pressing CTRL/Z (pressing the CTRL key and the 
Z key simultaneously) terminates the editing session. If an output file is open when CTRL/Z is 
pressed, all remaining lines in the block buffer and the input file are transferred (in that order) 
into the output file, all files are closed, and EDI exits. These actions occur whether EDI is in 
edit or input mode. If EDI is prompting for another file specification when CTRL/Z is pressed, 
all files are closed (including any open secondary input file), and EDI exits. If you press CTRL/Z 
as an input line terminator, that line is erased. 

7.8.13 Delete 

The Delete command causes a specified number of lines to be deleted in the following manner: 

• If n is given and is a positive number, the current line and n-1 following lines are deleted. 
The new current line is the line following the last deleted line. 

• If n is given and is a negative number, the current line is not deleted, but the specified 
number of lines that precede it are deleted. The line pointer remains unchanged. A negative 
value for n can be used only in block mode. 

• If n is not given, the current line is deleted, and the next line becomes the new current line. 

Format 

D[n] 

or 

D -n 

Example 

*D -5 [REfl 

Deletes the five previous lines in the block buffer. 
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7.8.14 Deleted Print 

The Delete & Print command performs the same function as the Delete command except that 
the new current line is printed when all the specified lines have been deleted. 

Format 

DP [n] 

or 

DP -n 

If n is not specified, +1 is assumed. A negative value for n can be used only in block mode. 

Example 

THIS IS LINE 1 
THIS IS LINE 2 
THIS IS LINE 3 
THIS IS LINE 4 

*DP 2 \Mi 
THIS IS LINE 3 

Deletes the first two lines and prints the current line. 

7.8.15 End 

The End command sets the current line pointer to the beginning of the last line of the block or 
input file. If EDI is in block mode, only line pointer positioning occurs. In line-by-line mode, 
all lines are copied from the input file to the output file until EOF is reached. The last line in 
the block or file is displayed if the Verify On command was issued. Note, however, that if the 
last line was deleted before you issued the End command, the pointer will be located past the 
text; thus, the last line will not be printed. The End command performs the same function as 
the Bottom command. 

Format 

E 

Example 

*V ON \M1 
*E \M] 

THIS IS THE LAST LINE 

Moves the current line pointer to the bottom of the block buffer (block mode is assumed). 
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7.8.16 Erase 

In line-by-line mode, the Erase command erases the current line. In this mode, n can only be 
1. In block mode, this command erases the current block buffer and the next n-1 blocks. If n 
is not specified, +1 is assumed. 

Format 

ERASE [n] 

Example 

♦ERASE 5 \Mi 

Erases the contents of the current block buffer and the next four blocks. These blocks are not 
written into the output file. 

7.8.17 ESCAPE Key 

Pressing the ESCAPE key causes the system to print the previous line in the block (block mode 
only). That line becomes the current line. Thus, you can back up through a block, one line at 
a time, by pressing a series of ESCAPE keys. Pressing the ESCAPE key is equivalent to typing 
NP-1 (Next & Print command) or pressing the ALTMODE key. 

If EDI is in input mode, the ESCAPE key acts like the RETURN key and terminates a line of 
input. The ESCAPE key also exits from input mode if it is the first character of the line. 

7.8.18 Exit 

The Exit command transfers all remairung lines in the block buffer and input file (in that order) 
into the output file, closes the files, and terminates the editing session. If a file specification is 
used, the output file is renamed to the specified file name. 

Format 

EX [filespec] 

Example 

*EX [RET] 

Terminates the editing session without renaming the output file. EDI then displays the following: 

[EXIT] 
EDI> 

The output filename.type is the same as the input filename.type. The version number is one 
greater than that of the input file. 
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7.8.19 Exit & Delete 

The Exit & Delete command functions in the same way as the Close & Delete command except 
that EDI also terminates. 

Format 

ED [filespec] 

Example 

*ED NEWFILE.DOC [RET] 

[EXIT] 

> 

Closes and deletes file; then, exits from EDI. 

7.8.20 File 

The File command — legal in line-by-line mode only — transfers lines from the input file to both 
the output file and a specified file, beginning with the current line, until a form-feed character 
is encountered as the first character in a line or until EOF is reached. At that time, the specified 
file is closed. The form-feed character is not included in the specified file. During the transfer, 
the original file remains intact (that is, all lines written to the specified file are also written to 
the normal output file, including the form feed). When the command is complete, the current 
line in the input file is one line beyond the form feed. 

If the specified file does not already exist, a new file is created. If the specified file does exist, 
the latest version of the file contains the new data. 

Format 

FIL filespec 

Example 

*FIL SEC. DAT [RET] 

Writes the contents of the input file, from the current line to the end, into both the output file 
and the file SEC.DAT. 

7.8.21 Find 

The Find command searches the block buffer or input file for a string, beginning at the line 
following the current line. The string must begin in column 1 of the line matched. The line 
pointer is positioned at the line containing the match. When the line containing the string is 
found, it is printed if the Verify On command is in effect. 

The Find command applies to the block buffer if EDI is in block mode and to the input file if 
EDI is in line-by-line mode. 

If a string is not specified, the line following the current line is considered a match. If n is 
specified, the nth occurrence of the string is found. 
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Format 

[n]F [string] 

Example 

*V ON [ret] 

*F LOOK \M] 

LOOK AT THE FIRST CHARACTER IN THE LINE. 

Searches the block buffer (or file) for a line that begins with LOOK and prints the line when 
the line is found. 

7.8.22 Form Feed 

The Form Feed command allows you to insert form feeds into the text to delimit pages. The 
form feed is inserted after the current line. The line containing the form feed then becomes the 
new current line. 

Format 

FF 

Example 



*P [RETJ 

THIS IS THE LAST LINE ON THE PAGE 

*FF [RET] 

Inserts a form feed into the text following the current line. 

7.8.23 Insert 

The Insert command inserts a string immediately following the current line. The string becomes 
the new current line. If a string is not specified, EDI enters input mode. 

Format 

I [string] 

Examples 

*I TEXT INSERT IN EDIT MODE [Ml 

Inserts a line of text immediately after the current line. 



*i \M1 

TEXT INSERT 1 IN INPUT MODE IreTI 
TEXT INSERT 2 IN INPUT MODE [RET] 
ETC. [M] 



Illustrates that the Insert command followed by the RETURN key causes EDI to switch to input 
mode. A series of new lines are then input following the current line. Also illustrates that 
pressing the RETURN or ESCAPE key as the only character in an input line causes EDI to return 
to edit mode and to prompt for a new command. 
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7.8.24 Kill 

The Kill command returns EDI to the initial command sequence without retaining the output 
file. When this command is executed, the input file is closed and the output file is deleted. 

Format 

KILL 

Example 

*KILL [ret] 
EDI> 

Deletes the output file and displays the prompt. 

At this point, you can return control to your CLI by pressing CTRL/Z or by typing a file 
specification for a file to be edited. 

7.8.25 Line Change 

The Line Change command is similar to the Change command except that all occurrences of 
stringl in the current line are changed to string2. A numeric value n preceding the command 
changes the current line and the next n-1 lines. If string2 is not given, all occurrences of stringl 
are deleted. New lines are printed if the Verify On command is in effect. 

If stringl is given, but EDI cannot locate the string in the current line, EDI prints [NO MATCH] 
and returns the asterisk ( * ) prompt. 

Format 

[n]LC /stringl /string2[/] 

Example 

THES ES THE LINE TO BE ESSUED. 

*V ON [M] 

*LC /ES/IS [Ml 

THIS IS THE LINE TO BE ISSUED. 

Corrects the errors in the line and prints the corrected line. 

7.8.26 List on Pseudo Device 

The List on Pseudo Device command functions in the same manner as the List on Terminal 
command except that the remaining lines in the block buffer (block mode) or the remaining 
lines of the input file (line-by-line mode) are listed on the pseudo device CL. In most systems, 
CL is the system line printer. 

Format 
LP 
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Example 

*LP [RETl 

Prints on the pseudo device CL all remaining lines in the block buffer or all remaining lines in 
the input file. 

7.8.27 List on Terminal 

The List on Terminal command prints on your terminal all remaining lines in the block buffer 
(block mode) or all remairung lines in the input file (line-by-line mode), beginning at the current 
line. At the end of the listing, the current line pointer is re-positioned to the top of the input 
file or block buffer. 

If terminal host synchronization is installed at system generation, you can control printing 
functions by pressing CTRL/O, CTRL/S, and CTRL/Q. To suppress printing at any point, press 
CTRL/O. Printing can be suspended temporarily by pressing CTRL/S and resumed by pressing 
CTRL/Q. 

Format 

LI 

Example 

*LI \Mi 

Prints on the terminal all remaining lines in the block buffer or all remaining lines in the input 
file. 

7.8.28 Locate 

The Locate command causes a search for a string, beginning at the line following the current 
line. The string may occur anywhere in the line sought. The line pointer is positioned to the 
line containing the match. When the line is located, it is printed if the Verify On command is 
in effect. 

If a string is not specified, the line following the current line is considered a match, and the 
line pointer is positioned there. If n is specified, the nth occurrence of string is located. 

Locate applies to the block buffer if EDI is in block mode and to the input file if in line-by-line 
mode. 

Format 

[n]L [string] 

Example 

*L PPY \M1 

Locates the line HAPPY DAYS ARE HERE AGAIN. 

EDI searches the file or block buffer and, if the Verify On command is in effect, prints the line 
when it is located. The current line pointer is set to the located line. 
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7.8.29 Macro 

The Macro command is used to define macros. Space is available for three macro definitions. 
The definition can be any legal EDI command or string of legal EDI commands connected by 
the concatenation character. 

If a numeric argument is to be passed to the macro at execution time, a percent sign ( % ) must 
be inserted in the macro definition at the point where the numeric argument is to be substituted. 
Then, the value passed with the Macro Execute command replaces the percent sign when the 
macro is executed. 

A macro definition may contain more than one percent sign. If it does, the single numeric value 
given in a Macro Execute command replaces each percent sign. However, a macro may not 
have two or more independent arguments. 

Format 

MACRO X definition 

Parameter 

X 

Specifies the macro number (1, 2, or 3). 
Examples 

♦MACRO 1 XL ABC&PA /ABC/DEF [RET] 
*M1 10 Wf] 

Finds the nth occurrence of the string ABC in the current block and replaces that occurrence 
and all remaining occurrences within the block with the string DEF. Executes the macro and 
searches for the tenth and succeeding occurrences of ABC. 

♦MACRO 1 PA /ABC/DEF/&PA /GHI/JKL/tREN [RET] 
*5M1 [RET] 



Changes all occurrences of the strings ABC and GHI to DEF and JKL respectively. The 
substitution is made in the current block and the next four blocks (five blocks in all). 

7.8.30 Macro Call 

The Macro Call command allows you to retrieve up to three macro definitions previously 
stored in a file. The macro definitions must contain only the "definition" portion of the Macro 
command. The macro definitions are stored in successively numbered macros: the first definition 
becomes macro 1, and so on. 

The file used to store the macro definitions must be the latest version of file MCALL — that is, 
MCALL;n. The file type must be null or blank. If the macro definitions to be loaded are in a file 
of another name, you can use the Peripheral Interchange Program (PIP) with the New Version 
(/NV) subswitch, to rename the file. (Refer to Chapter 12 for descriptions of PIP commands.) 
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Format 

MC 

Strings of concatenated EDI commands can be written as EDI macro definitions, and up to three 
EDI macro definitions can be stored in file MCALL;n. The Macro Call command is used to call 
the latest version of file MCALL and move the three definitions into the macro storage area. 
Then you can execute the desired macro without having to type the complete command. 

Macro calls may not be nested. 

The concatenation character may precede, but not follow, a macro call. 

Example 

*Mc mi] 

Retrieves the macro definitions stored in file MCALL;n, where n represents the latest version of 
the file MCALL. 

7.8.31 Macro Execute 

The Macro Execute command executes a macro n times while passing it an optional numeric 
argument a. If a macro numeric argument is defined with the percent sign ( % ) in the macro 
definition, the numeric argument contained in this command is passed for each execution of the 
macro. Before a macro can be executed, it must either have been defined by means of a Macro 
command or called with a Macro Call command. 

Use the Macro Execute command to execute any one of the three macro definitions stored in 
the EDI macro storage area any number of times. 

Format 

[n]Mx [a] 

Parameters 

n 

Specifies the number of times the macro is to be executed. 

X 

Specifies the macro number (1, 2, or 3). 

a 

Specifies the numeric argument to be passed when the macro is executed (ignored if the 
argument % is not present in macro definition). 

Examples 

*2M1 [ret] 

Executes macro number 1 twice. 
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*3M2 5 [RET] 

Executes macro number 2 three times, and passes the numeric argument 5 each time the macro 
is executed. 

The example in Section 7.10.4 illustrates how to use the EDI macro commands when editing a 
file. 

7.8.32 Macro Immediate 

The Macro Immediate command defines and executes a macro in one step. The definition is 
enclosed within angle brackets and is identical to that of the Macro command. The definition 
is copied into the macro 1 storage area and immediately executed n times. The macro may 
also be subsequently executed by entering an Ml command. The command is equivalent to the 
following two macro commands: 

MACRO 1 definition 
nMl 

Format 

[n] < definition > 

Example 

*<L ABC&C /ABC/DEF> [RETI 

Searches the current block buffer for the string ABC and, when ABC is located, changes the 
string to DEF. This macro is stored as macro number 1. 

The example in Section 7.10.3 illustrates the use of the Macro Immediate command. 

7.8.33 Next 

The Next command moves the current line pointer backwards and forwards in the file. A 
positive number moves the current line pointer n lines beyond the current line. A negative 
number moves the current line pointer backward n lines. 

Format 

N[n] 

or 

N -n 

If n is not specified, a value of +1 is assumed. A negative value for n can be used only in the 
block mode. 

Example 

*N -5 \M] 

Moves the current line pointer back five lines only in block mode. 



7-30 Line Text Editor (EDI) 



7.8.34 Next & Print 

The Next & Print command has the same effect as the Next command except that the new 
current line is printed. 

Format 

NP [n] 

or 

NP -n 

The following conventions can be used in place of issuing an NP command: 

• Pressing the RETURN key is the same as an NP+1 command. 

• Pressing the ESCAPE or ALTMODE key while in the block mode is the same as an NP-1 
command. 

• If n is not specified, then a value of +1 is assumed. 
Example 

LINE 1 OF THE FILE 
LINE 2 OF THE FILE 
LINE 3 OF THE FILE 
LINE 4 OF THE FILE 

Assumes the previous four lines are contained in the file and the line pointer is at the first line. 
If the following command lines are issued, EDI returns the following listing: 

*NP 2 [Ml 

LINE 3 OF THE FILE 

• Mi 

LI NE 4 OF THE FILE 

* [ESCi 

li ne 3 of the file 

* [esc] 

line 2 of the file 

7.8.35 Open Secondary 

The Open Secondary command opens the specified secondary input file. The primary input file, 
if any, remains open. Subsequent text is read from the primary input file until the secondary 
input file is selected by means of the Select Secondary (SS) command for input. 

Format 

OP filespec 

Example 

*0P RICKS. MAC [M] 

*SS [Ml 

*REA 1 [RET] 

Opens the file RICKS.MAC as a secondary input file and then reads in the first block. 
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7.8.36 Output On/Off 

The Output On/Off command, used only in the line-by-line mode, allows you to continue or 
discontinue the transfer of text to the output file. Output On is the default condition; it is 
automatically reestablished each time a Close command is issued. 

Format 

OU [ON] 

or 

OU OFF 

If neither ON nor OFF is specified, ON is assumed. 
Example 

iBL OFF IMl 
*0U OFF [ret] 

« 5 [M] 
hOu on \M\ 

Shows how to bypass five lines of text in the input file so that these lines are not written into 
the output file. The command lines perform the following tasks: 

• The first command line sets line-by-line mode. 

• The second command line disables the transfer of text to the output file. 

• The third command line bypasses five consecutive lines of text from the input file. 

• The fourth command line reenables the transfer of text to the output file. 

7.8.37 Overlay 

The Overlay command deletes n lines and replaces them with any number of lines that you 
type. If n is not specified, the current line is deleted and replaced with the lines typed. When 
you enter the Overlay command, EDI enters input mode. All text that you type goes into the 
file until you press the RETURN key as the only character in an input line. 

Format 

0[n] 

Example 

o 2 [m 

Deletes two lines and causes EDI to enter input mode. 
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7.8.38 Page 

The Page command causes EDI to enter block mode, if not already in it, and read page n into 
the block buffer. A page is delimited by form feeds. If n is less than the current page number, a 
TOF command is performed first. TOF processing writes the input file to the output file, closes 
both files, and then opens the latest version of the file. 

If n is greater than the current page number, the necessary number of Renew commands is 
executed to read page n into the block buffer. This command can be used in block mode only. 

Format 
PAGn 

Example 

*AG 1 [RET] 

[00050 LINES READ IN] 

[00050 LINES READ IN] 

[00050 LINES READ IN] 

[00050 LINES READ IN] 

[00017 LINES READ IN] 

[PAGE 1] 
* 

Shows a quick way to get to the last block in a file that contains no form-feed page delimiters. 
EDI's page count is not incremented unless it encounters form-feed characters or an EOF mark. 
Thus, in a file without form feeds (that is, most files), EDI renews the block buffer until it 
encounters an EOF mark. Note that the final block contains 17 lines of text. 

7.8.39 Page Find 

The Page Find command performs the same function as the Find command except that successive 
blocks are searched until the nth occurrence of the string has been found. The contents of the 
block buffer and the blocks between the current block and the block in which the nth occurrence 
of the string is located are copied into the output file. 

The string must begin in column 1 of the matched line. The line is printed if the Verify On 
command is in effect. This command can be used only in block mode. 

Format 

[n]PF string 

7.8.40 Page Locate 

The Page Locate command causes a search of the current block, starting at the line following 
the current line, and of successive blocks until the nth occurrence of the string has been located. 
Text from the current block buffer is written into the output file. The string can occur any place 
in the lines checked. The line is printed if the Verify On command is in effect. This command 
can be used only in block mode. 
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Format 

[n]PL string 

This command is used in the same manner as the Locate command except that the specified 
string can be in a block other than the current block. 

PL leaves the current line pointer at EOF if it cannot locate the string. 

7.8.41 Paste 

The Paste command is identical to the Line Change command except that all lines remaining 
in the input file or block buffer are searched and all occurrences of stringl are replaced with 
string2. Modified lines are printed if the Verify On command is in effect. If stringl is given, 
but no match is found, EDI returns the asterisk (*) prompt. When the command completes, 
the line pointer is at the top of the buffer or input file. 

Format 

PA /stringl /string2[/] 

Example 

YIGER. YIGER. BURNING BRIGHT 
IN YHE FORESYS OF YHE NIGHY 

*PA nil [RET] 

Corrects the errors in the previous lines. 

If the Verify On command is in effect, all corrected lines are printed. To discontinue printing, 
press CTRL/O. 

7.8.42 Print 

The Print command prints the current line and the next n-1 lines on the temunal. The last line 
printed becomes the new current line. If n is not specified, a value of 1 is assumed. 

Figure 7-1 illustrates both the Print and the Type commands. 

Format 

P[n] 

7.8.43 Read 

The Read command reads the next n blocks of text into the block buffer. If a block is already 
in the buffer, the new block or blocks are appended to it. 

EDI must be in block mode before this command can be executed. 

A Read command cannot exceed the buffer capacity. If you issue a Read command that is too 
large, EDI fills its buffer and then issues the following message: 

[BUFFER CAPACITY EXCEEDED BY] 
<offending line> 
[LINE DELETED] 
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You may get this message after issuing a Read n command, where n is 2 or larger, unless you 
have used the Size command to reduce the number of lines per block below its initial number. 

Format 

REA [n] 
If n is not specified, a value of 1 is assumed. The value of n must be positive. 

Example 

♦ SIZE 15 [Hi] 
*REA 4 (Ml 

Reads four 15-line blocks of the input file into the block buffer. 

7.8.44 Renew 

The Renew command writes the current block buffer into the output file and reads a new block 
from the input file. The optional value n is a repetition count: if you specify n, the process is 
repeated n times. The intermediate blocks are written into the output file and the last block 
is left in the block buffer. If n is not specified, a single Renew process is performed. This 
command may be used oiUy in block mode. Refer to Section 7.3 for information on how EDI 
block buffers are processed. 

Format 

REN [n] 

Example 

*REN 10 [m 

Transfers consecutively 10 blocks from the input file to the block buffer. The initial contents of 
the block buffer and the next nine blocks are transferred consecutively to the output file. The 
current line pointer points to the first line in the tenth block, which is currently in the block 
buffer. 

7.8.45 RETURN Key 

Pressing the RETURN key in edit mode causes the next line in the file or block buffer to be 
printed. That line becomes the current line. Thus, you can scan through a file or block, one 
line at a time, by pressing a series of RETURN keys. This command is equivalent to NP+1 (Next 
& Print command). 

In input mode, pressing the RETURN key causes EDI to change from input mode to edit mode. 
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7.8.46 Retype 

The Retj^e command replaces the current line with a string. If a string is not specified, the line 
is deleted. 

Format 

R [string] 

Example 

*R THIS IS A NEW LINE IRET] 

Replaces the current line with the string THIS IS A NEW LINE. 

7.8.47 Save 

The Save command causes the current line, and the next n-1 lines, to be saved in the specified 
file. If the file already exists, a new version is created. 

If no file is specified, the save file generated has the name SAVE.TMP. Save puts the temporary 
file in the directory on the device for the file you are editing. 

The input file or buffer information that is transferred to the save file remains intact. The new 
current line is the last line saved. The Save command does not delete lines in the block buffer 
or input file. 

Format 

SA [n] [filespec] 

Example 

You can save and later insert small groups of lines in several places in an output file by using 
the Save and Unsave commands. For example, a file called EDIT.MAC contains six lines that 
you want to insert at several points in another file called HELP.MAC. You should proceed, as 
follows: 

1. Start an editing session using EDIT.MAC as the input file. 

2. Locate the lines to be inserted into HELP.MAC. 

3. Issue a SA 6 command. (This copies the six lines to be saved into the file SAVE.TMP.) 

4. Issue the Kill command to terminate the editing session. 

5. Start a new editing session using HELP.MAC as the input file. 

6. Locate each place where the six lines are to be inserted and issue the Unsave command. 

7. Make further edits to the input file, as desired, or issue the Exit command. 
EDI does not delete the save file. It remains on the specified volume until deleted. 
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7.8.48 Search & Change 

The Search & Change command causes a search for stringl in the block buffer (block mode) or 
input file (line-by-line mode), beginning at the current line. The string may occur anywhere in 
the line. When stringl is located, it is replaced by string2. The located line becomes the current 
line. 

If stringl is not specified, EDI prints the error message [ILL STRING CONST]. The new current 
line is printed if the Verify On command is in effect. If stringl is given, but EDI cannot locate 
the string, EDI returns the asterisk ( * ) prompt and the line pointer is positioned at the EOF or 
at the bottom of the block buffer. 

Format 

SC /stringl/string2[/] 

Example 

*V ON \M] 

*SC /THES/THIS/ [Ml 

THIS IS THE LINE TO BE ISSUED. 

Corrects the following text: 

THES IS THE LINE TO BE ISSUED. 

The corrected line is printed because the Verify On command is in effect. 

7.8.49 Select Primary 

The Select Primary command selects the primary file for input. It allows you to reestablish the 
primary input file as the file from which text is read. 

Format 
SP 

Example 

*op SECOND. ^ac [Ml 

*ss [HD 

*REN 10 [RETl 
♦ CLOSES \M} 

*SP [Ml 

Directs EDI to perform the following tasks: 

1. Open the secondary file SECOND.MAC. 

2. Select SECOND.MAC as the secondary input file. 

3. Read 10 consecutive block buffers from the secondary input file into the block buffer. The 
first nine blocks are automatically transferred to the output file. 

4. Close the secondary input file SECOND.MAC. The secondary file need not be closed before 
the primary file is reselected for input. 

5. Reselect the primary input file for input. 
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7.8.50 Select Secondary 

With the Select Secondary command, you select the secondary file as the input file. 
Format 

ss 

Refer to Section 7.8.49 for an example of the Select Secondary command. 

Note 

To add text to the output file from a secondary input file, you must first open the secondary 
input file and select it for input. 

7.8.51 Size 

The Size command allows you to specify the maximum number of lines to be read into the 
block buffer on a single Read or Renew command. The default value for Size depends on your 
exact system configuration. Initially, EDI determines how much buffer space it has and divides 
that by 132io, the maximum line size, to set the number of lines read in. In no case can it be 
less than 38 lines. (See the discussion of block mode in Section 7.3.) 

Format 

SIZEn 

Example 

♦SIZE 50 [RET] 

Conditions EDI to read 50 lines into the block buffer during a single Read or Renew command. 

7.8.52 Tab On/Off 

The Tab On/Off command turns automatic tabbing on or off. The automatic tab feature is 
useful for MACRO-11 language input. Tab Off is the default at the start of an editing session. 
When Tab On is in effect, a tab (equivalent to eight spaces) is automatically inserted at the 
beginning of each input line unless the line either begins with a label followed by a colon ( : ) 
or contains a semicolon ( ; ) in the first column. 

Format 

TA [ON] 

or 

TAOFF 

If neither ON nor OFF is specified when a TAB command is issued, ON is assumed. 
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Examples 

*TA ON [Ml 

*i [ret] 

; THIS IS A SAMPLE OF TABBING. \Mi 
THIS LINE GETS A TAB [RET] 
1: THIS ONE DOESN'T [Ml 
END \Mi 
[RET] 

*TA OFF [Ml 
*N -3 [M] 
*.P 4 \M} 
: THIS IS A SAMPLE OF TABBING. 

THIS LINE GETS A TAB 
1: THIS ONE DOESN'T 

END 

7.8.53 Top 

The Top command sets the current line pointer to the top of the current block (in block mode) 
or to the top of the file (in line-by-line mode). When the current line pointer is positioned using 
the Top command, you can enter lines preceding the first line in the block or file. 

The Top command differs from TOF in the following ways: 

• In line-by-line mode, the Top command creates a new file and moves the current line 
pointer to the top of the file. Unlike the TOF command, it does not cause EDI to return to 
block mode. 

• In block mode, the Top command moves the current line pointer to the top of the current 
block and does not create a new output file. The TOF command moves the current line 
pointer to the top of the file and creates a new output file. 

Format 

T 

Example 

*T [RET] 

Directs the current line pointer to the top of the current block in block mode. 

7.8.54 Top Of File 

The Top of File (TOF) command creates a new version of the file and returns the current line 
pointer to the first line of the file. The TOF command copies the input file into the output file, 
closes both, and then opens the latest version of the file as the input file. If you issue this 
command when in line-by-line mode, EDI switches to block mode after saving the edited data. 
The first block is read into the block buffer. 

Format 
TOF 
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Example 

*uc OFF nm 

*I this line is entered in lowercase |RET| 

*UC ON [RET] 

*I this line is converted to uppercase |RET| 

Creates the following lines in the output file if the input terminal is capable of generating 
lowercase input: 

this line is entered in lower case 
THIS LINE IS CONVERTED TO UPPER CASE 

However, in both instances, the letters are converted to uppercase before the file is closed. 

To create a file containing lowercase characters, use the MCR command SET /L0WER=T1: oi 
the DCL command SET TERM LOWER and the EDI Uppercase Off command. 

7.8.58 Verify On/Off 

The Verify On/Off command controls the display of lines specified by the Locate and Change 
commands. Use the Verify On command to display a line located by the Locate command oi 
to display a line changed by the Change command. Use the Verify Off command to inhibit the 
display of these lines. The Verify On command is the default when EDI is started. 

Format 

V[ON] 

or 

VOFF 

If neither ON nor OFF is specified, ON is assumed. 
Example 

*V OFF \Mi 
*L VERIFY [HET] 

*p [ret] 

LINE IS PRINTED AUTOMATICALLY IF VERIFY IS ON 

*N -2 [m] 

*V ON [H] 

*L VERIFY \Mi 

LINE IS PRINTED AUTOMATICALLY IF VERIFY IS ON 

Issues the Print command to demonstrate that the desired line has been located when the 
Verify Off command is in effect, but when the Locate command is reissued with the Verify On 
command, EDI automatically prints the line. 
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Examples 

*TA ON \M1 
*I [RET] 

; THIS IS A SAMPLE OF TABBING. 
THIS LINE GETS A TAB HHl 
1: THIS ONE DOESN'T [RET] 
END [RE] 

fRET] 

*TA OFF [RET] 
*N -3 \M] 

*P 4 [M] 

; THIS IS A SAMPLE OF TABBING. 

THIS LINE GETS A TAB 
1: THIS ONE DOESN'T 

END 

7.8.53 Top 

The Top command sets the current line pointer to the top of the current block (in block mode) 
or to the top of the file (in line-by-line mode). When the current line pointer is positioned using 
the Top command, you can enter lines preceding the first line in the block or file. 

The Top command differs from TOF in the following ways: 

• In line-by-line mode, the Top command creates a new file and moves the current line 
pointer to the top of the file. Unlike the TOF command, it does not cause EDI to return to 
block mode. 

• In block mode, the Top command moves the current line pointer to the top of the current 
block and does not create a new output file. The TOF command moves the current line 
pointer to the top of the file and creates a new output file. 

Format 

T 

Example 

*T [RET] 

Directs the current line pointer to the top of the current block in block mode. 

7.8.54 Top Of File 

The Top of File (TOF) command creates a new version of the file and returns the current line 
pointer to the first line of the file. The TOF command copies the input file into the output file, 
closes both, and then opens the -latest version of the file as the input file. If you issue this 
command when in line-by-line mode, EDI switches to block mode after saving the edited data. 
The first block is read into the block buffer. 

Format 
TOF 
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Example 

*TOF [ret] 

Writes the previously edited pages into the output file, resets the current line pointer to the top 
of the input file, and reads the first block into the block buffer. 

7.8.56 Type 

The Type coiiunand is similar to the Print command (Section 7.8.42). In line-by-line mode, 
the two are identical. In block mode, the Type command does not move the line pointer after 
displaying the requested text unless the end-of-block is encountered. In this case, the line 
pointer remains at the last line before the end-of-block. Figure 7-1 illustrates both the Print 
and Type commands. The arrow in the figures represents the line pointer. 

If n is not specified, a value of 1 is assumed. 

Format 

TY[n] 

7.8.56 Unsave 

The Unsave command retrieves all the lines in a specified file and copies them after the current 
line. If no file is specified, the default file is SAVE.TMP. The new current line pointer is 
positioned at the last line retrieved from the file. The file used in this command can be any 
text file. It is often the file created with the Save command. 

Format 

UNS [filespec] 

Example 

*UNS SEC. DAT ;1 [RET] 

Retrieves all the lines in the file SEC.DAT;1 and inserts them after the current line. 

Section 7.10.2 contains an example that uses the Save and Unsave commands. 

7.8.57 Uppercase On/Off 

The Uppercase On/Off command allows you to enter lowercase letters from a terminal and 
have them converted to uppercase letters. If the Uppercase Off command is issued, all input 
letters are accepted as they are entered, including the EDI commands. 

Format 

UC [ON] 

or 

UCOFF 

If neither ON nor OFF is specified, then ON is assumed. 
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Figure 7-1: Line Pointer Position for ttie Type Command and ttie Print Command 
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Example 

*UC OFF \m} 

*I this line is entered in lowercase |RET| 

*UC ON [RET] 

*I this line is converted to uppercase |RET| 

Creates the following lines in the output file if the input terminal is capable of generating 
lowercase input: 

this line is entered in lower case 
THIS LINE IS CONVERTED TO UPPER CASE 

However, in both instances, the letters are converted to uppercase before the file is closed. 

To create a file containing lowercase characters, use the MCR command SET /LOWER=TI: or 
the DCL command SET TERM LOWER and the EDI Uppercase Off command. 

7.8.58 Verify On/Off 

The Verify On/Off command controls the display of lines specified by the Locate and Change 
commands. Use the Verify On command to display a line located by the Locate command or 
to display a line changed by the Change command. Use the Verify Off command to inhibit the 
display of these lines. The Verify On command is the default when EDI is started. 

Format 

V [ON] 

or 

V OFF 

If neither ON nor OFF is specified, ON is assumed. 
Example 

*V OFF \M1 
*L VERIFY [Hi] 

*p mn 

LINE IS PRINTED AUTOMATICALLY IF VERIFY IS ON 

*N -2 HH] 

*V ON IM] 

*L VERIFY [M] 

LINE IS PRINTED AUTOMATICALLY IF VERIFY IS ON 

Issues the Print command to demonstrate that the desired line has been located when the 
Verify Off command is in effect, but when the Locate command is reissued with the Verify On 
command, EDI automatically prints the line. 
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7.8.59 Write 

The Write command causes the entire contents of the block buffer to be written into the output 
file. The block buffer is then erased. 

EDI must be in block mode before this command can be executed. 

Format 

w 

Example 



*W [RET] 
*REA 2 [RET] 

Writes the block buffer into the output file and then erases it. Next, the next two blocks are 
read into the block buffer. 

7.9 EDI Usage Notes 

The following points contain general information involving restrictions on use of EDI, system 
device considerations, and general usage rules: 

• EDI can operate only on Files-11 format files; it rejects all other file formats. 

• The output file generated by EDI always resides on the same device as the input file. The 
output file carmot be directed to another device. For example, to edit a file on DECtape 
and store the resulting file on disk, do one of the following: 

— Transfer the file to disk and perform the editing there. 

— Edit the file on DECtape and then use the Peripheral Interchange Program (PIP) or File 
Transfer Utility Program (FLX) to transfer the file to disk. 

• To use a device other than SY, movmt it with the MOUNT command. 

• To edit a version of a file other than the latest one, explicitly state the desired version 
number in the file specification. This file is opened as the input file. The version number 
of the output file is one greater than the latest version of the file. 

• Some EDI commands (such as TOF and Top, when used in line-by-line mode) implicitly 
generate multiple versions of a file. In the execution of such commands, EDI copies the 
remainder of the input file into the output file and closes both of them. It then opens the 
latest version of the file and uses it as input. This ensures the editing of the latest version 
of the file and provides periodic backup. To delete any unwanted versions, use PIP with 
the Purge (/PU) switch or the DCL command DELETE. 

• EDI accepts variable length input lines up to 132io characters long. 

• The record type of output files edited by EDI is always variable-length. 

• EDI preserves the record attributes of the input file. For example, the FORTRAN carriage 
control attribute is preserved in the output file. 
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• Line-feed characters may be entered in files, but they are interpreted by EDI as termination 
characters. You should avoid using them because they cause unpredictable results when 
the file is edited a second time. 

• EDI cannot process a file that contains embedded carriage control characters, such as 
PIP directory listings and Task Builder (TKB) map files. To reformat such a file for EDI 
processing, copy the file to a DOS-11 volume and then back to your original volume by 
using FLX. You can then use EDI to process the file. 

7.10 Editing Operation Examples 

Examples of the following editing operations are included in this section to illustrate how the 
various EDI commands can be used: 

• A file is edited using a few basic EDI commands. 

• Two save files are generated, modified, and appended to the original file. Any closed file 
may be appended to or inserted within an open file in the manner shown in Section 7.10.2. 

• An immediate macro command is defined and executed in a single step. 

• A file containing errors is edited by using the macro commands. 
Numbered explanations follow each example. 

7.10.1 File Editing Example 

>EDl PRTBLD.CMD O 

[PAGE 1] 

4P * O 

': COMMAND FILE TO BUILD 

; PRNT SYMBIONT 

; FOR RSX-llM-PLUS MAXXED 

; SYSTEM 

[1 . 54] PRT/MM/-CP , LP : =PRTBLD/MP 
; OPTIONS 

STACK=40 

PAR=PARK:0: 10000 

UNITS=4 

TASK=PRT. . . 

ASG=C0:2.LP:3 

PRI=60 

UC=[10.1] 

SPECIFY 

SPECIFY FLAG WHICH CONTROLS 

FILE DELETION AFTER PRINTING 

TO ENABLE DELETION USE 

GBLPAT=PRT ; $DELET : 1 
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TO INHIBIT DELETION USE 

DEFAULT FROM ASSEMBLY IS 
FILE DELETION ENARBLED 

GBLPAT=PRT:$DELET 

/ 

[*EOB*] 

*T @ 

[PAGE 1] 

=iPL PRNT O 

PRNT SYMBIONT 
*C /RN/RIN/ @ 

PRINT SYMBIONT 

[ReTI © 

FOR RSX-llM-PLUS MAXXED SYSTEM 

*c /xx/pp/ O 

FOR RSX-llM-PLUS MAPPED SYSTEM 
^? 3 ® 

[1 , 54] PRT/MM/-CP . LP : =PRTBLD/MP 
nC /-CP,/CP, O 

[1 . 54] PRT/MM/CP , LP : =PRTBLD/MP 
rf>L PAR= <B 

PAR=PARK: 0:10000 
*C /RK/R4K/ <D 

PAR=PAR4K:0: 10000 
■«P -3 ® 

; OPTIONS 

=iAP INPUT ® 

; OPTIONS INPUT 
4PL UC <D 

UC=[10,1] 
iC /UC/UIC/ (D 

UIC=[10,1] 

* fRETl (D 



[RETI 

SPECIFY 
«P ® 

SPECIFY FLAG WHICH CONTROLS 
4>L INH (D 

TO INHIBIT DELETION USE 

*i <E) 

6BLPAT=PRT : $DELET : 

fRET] 

*L RB ® 
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; FILE DELETION ENARBLED 

*c mi ® 

; FILE DELETION ENABLED 

* [Ml 

* [ret] ® 
GBLPAT=PRT:$DELET 
*AP :1 ® 

GBLPAT=PRT : $DELET : 1 
4cT0F ® 

[PAGE 1] 
*P * © 

COMMAND FILE TO BUILD 

PRINT SYMBIONT 

FOR RSX-llM-PLUS MAPPED SYSTEM 



[1 , 54] PRT/MM/CP . LP : =PRTBLD/MP 
OPTIONS INPUT 



STACK=40 

PAR=PAR4K: 0:10000 

UNITS=4 

TASK=PRT . . . 

ASG=C0:2,LP:3 

PRI=60 

UIC=[10.1] 



SPECIFY FLAG WHICH CONTROLS 
FILE DELETION AFTER PRINTING 

TO ENABLE DELETION USE 

GBLPAT=PRT : $DELET : 1 

TO INHIBIT DELETION USE 

GBLPAT=PRT : $DELET : 

DEFAULT FROM ASSEMBLY IS 
FILE DELETION ENABLED 

GBLPAT=PRT : $DELET : 1 

/ 

[*EOB*] 

*EX ® 

[EXIT] 



Notes for File Editing Example 

O EDI opens file PRTBLD.CMD for editing. 

O The P command (Print) prints the contents of the file, and the following errors are detected 
in the text of the file: 

PRNT should be PRINT. 
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MAXXED should be MAPPED. 

/-CP should be /CP. 

INPUT should be appended to the line containing the word OPTIONS. 

PARK should be PAR4K. 

UC should be UIC. 

The line containing ; SPECIFY should be deleted. 

The comment line containing the format used to inhibit deletion is missing. 

ENARBLED should be ENABLED. 

A :1 should be appended to the line following the word $DELET. 

The end of buffer is reached and EDI prints the EOB message. 

© The T command (Top) moves the line pointer to the top of the file and editing begins. 

O The PL command (Page Locate) locates and displays the first line in error. 

The C command (Change) corrects the line and displays the corrected line. 

© The RETURN key moves the line pointer to display the next line in error. 

O The C command (Change) corrects the line and displays the corrected line. 

® The NP command (Next & Print) locates and displays the next line in error. 

© The C command (Change) corrects the line and displays the corrected line. 

® The PL command (Page Locate) locates and displays the next line in error. 

© The C command (Change) corrects the line and displays the corrected line. 

© A line in error was bypassed by mistake; therefore, an NP command (Next & Print) is 
issued to move the line pointer back three lines. 

® The AP command (Add & Print) corrects the line and displays the corrected line. 

© The PL command (Page Locate) locates and displays the next line in error. 

© The C command (Change) corrects the line and displays the corrected line. 

© Pressing the RETURN key twice moves the line pointer down two lines and locates the next 
line in error. 

© The DP command (Delete & Print) deletes the line containing ; SPECIFY and prints the 
next line. 

© The PL command (Page Locate) locates the point in the file where the new comment lines 
are to be inserted. 

© The I command (Insert) switches EDI from edit mode to input mode, and allows two lines 
to be entered. Pressing the RETURN key twice svdtches input mode back to edit mode. 

® The PL command (Page Locate) locates the next line in error. 

© The C command (Change) corrects the spelling error and displays the corrected line. 

© Pressing the RETURN key twice moves the line pointer down two lines and locates the last 
line in error. 

® The AP command (Add & Print) appends :1 following the word $DELET. 
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© The TOF command (Top of File) moves the line pointer to the top of the file. 

© The P command (Print) prints the complete file with all corrections. 

® The EX command (Exit) closes the file and terminates the editing session. 

7.10.2 Save and Unsave Example 

EDI>START.DAT O 

[PAGE 1] 
*LI O 
THIS IS LINE 1 PAGE 1 
THIS IS LINE 2 PAGE 1 
THIS IS LINE 3 PAGE 1 
THIS IS LINE 4 PAGE 1 
THIS IS LINE 5 PAGE 1 
[*EOB*] 

*T e 

«SA S SAVl.DAT O 

*T 

*SA 5 SAV2.DAT O 

*CL e 

EDI>SAV1.DAT © 

[PAGE 1] 

*LI © 

THIS IS LINE 1 PAGE 1 

THIS IS LINE 2 PAGE 1 

THIS IS LINE 3 PAGE 1 

THIS IS LINE 4 PAGE 1 

THIS IS LINE 5 PAGE 1 

[*EOB*] 

»PA /PAGE 1/PAGE 2/ © 

THIS IS LINE 1 PAGE 2 
THIS IS LINE 2 PAGE 2 
THIS IS LINE 3 PAGE 2 
THIS IS LINE 4 PAGE 2 
THIS IS LINE 5 PAGE 2 
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EDI>SAVE2.DAT <D 

[PAGE 1] 

*LI ® 

THIS IS LINE 1 PAGE 1 

THIS IS LINE 2 PAGE 1 

THIS IS LINE 3 PAGE 1 

THIS IS LINE 4 PAGE 1 

THIS IS LINE 5 PAGE 1 

[*EOB*] 

*PA /PAGE 1/PAGE 3/ <D 

THIS IS LINE 1 PAGE 3 

THIS IS LINE 2 PAGE 3 

THIS IS LINE 3 PAGE 3 

THIS IS LINE 4 PAGE 3 

THIS IS LINE 5 PAGE 3 

>kCL (D 

EDI>START . DAT ® 

[PAGE 1] 

*B0 ® 

THIS IS LINE 5 PAGE 1 

*UNS SAVl.DAT <D 

*UNS SAV2.DAT 

*T <E> 

*LI ® 

THIS IS LINE 1 PAGE 1 

THIS IS LINE 2 PAGE 1 

THIS IS LINE 3 PAGE 1 

THIS IS LINE 4 PAGE 1 

THIS IS LINE 5 PAGE 1 

THIS IS LINE 1 PAGE 2 

THIS IS LINE 2 PAGE 2 

THIS IS LINE 3 PAGE 2 

THIS IS LINE 4 PAGE 2 

THIS IS LINE 5 PAGE 2 

THIS IS LINE 1 PAGE 3 

THIS IS LINE 2 PAGE 3 

THIS IS LINE 3 PAGE 3 

THIS IS LINE 4 PAGE 3 

THIS IS LINE 5 PAGE 3 

[*EOB*] 

*EX ® 

[EXIT] 

Notes for Save and Unsave Example 

O EDI opens file START.DAT. 

@ The LI command (List on Terminal) prints the file. 

O The T command (Top) moves the line pointer to the top of the block. 

O The SA command (Save) saves the five lines in a separate file. 

© The T command (Top) moves the line pointer to the top of the file. 

© The SA command (Save) generates a second saved file. 

© The CL command (Close) closes the primary input file. 
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© EDI opens the first save file. 

O The LI (List on Tenninal) command displays the file. 

(D The PA command (Paste) changes PAGE 1 to PAGE 2 in all lines. 

® The CL command (Close) closes the first save file. 

® EDI opens the second save file. 

® The LI command (List on Terminal) displays the contents of the file. 

<D The PA command (Paste) changes PAGE 1 to PAGE 3 in all lines. 

® The CL command (Close) closes the second save file. 

® EDI opens the original input file. 

(D The BO command (Bottom) locates the last line in the file. 

® Two UNS commands (Unsave) append the two save files to the original input file. 

® The T command (Top) moves the line pointer to the top of the file. 

® The LI command (List on Terminal) displays the contents of the combined file. 

® The EX command (Exit) doses the input file and terminates the editing session. 

7.10.3 Macro Immediate Example 

EDI>START.DAT O 

[PAGE 1] 
*LI @ 

ABC IN LINE 1 - ABC 
ABC IN LINE 2 - ABC 
ABC IN LINE 3 - ABC 
ABC IN LINE 4 - ABC 
ABC IN LINE 5 - ABC 



ABC IN LINE n - ABC 
[*EOB*] 

*4<F ABCfcC /ABC/DEF/> 
ABC IN LINE 1 - ABC 
DEF IN LINE 1 - ABC 
ABC IN LINE 2 - ABC 
DEF IN LINE 2 - ABC 
ABC IN LINE 3 - ABC 
DEF IN LINE 3 - ABC 
ABC IN LINE 4 - ABC 
DEF IN LINE 4 - ABC 
*EX O 



Notes for Macro Immediate Example 

O EDI opens file START.DAT. 

@ The LI command (List on Terminal) prints the file. 
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The immediate macro is defined and executed. It finds the first four lines that start with 
ABC and changes the first occurrence of the string ABC to DEF. The F command (Find) 
causes the line to be printed before the change. The C command (Change) causes the line 
to be printed after the change. 

The EX command (Exit) closes the file and terminates the editing session. 



7.10.4 Macro Commands Example 

EDI> START. DAT O 
[PAGE 1] 

* LI @ 
THIS LITTLE FILE HAS 
MANY CONNON ETTORS SO 
WE CAN SHOW YOU HOW 
YHE MACRO CONNANDS CAN 
BE USED. 

FIRST, YHE DESIRED MACRO 
MUST BE DEFINED; YHE LINE 
POINTER IS MOVED TO A LINE 
WITH AN ETTOR; AND YHEN, YHE 
MACRO EXECUTE CONNAND 
IS ISSUED TO COTTECT YHE 
ETTOR 
[*EOB*] 

* MACRO 1 C /NN/MM/ ® 
♦MACRO 2 SC /TT/RR/ 

* MACRO 3 PA /YHE/THE/ 
*M3 O 

THE MACRO CONNANDS CAN 
FIRST. THE DESIRED MACRO 
MUST BE DEFINED: THE LINE 
WITH AN ETTOR. AND THEN. THE 
IS ISSUED TO COTTECT THE 
*NP 2 O 

MANY CONNON ETTORS SO 
*M1 O 

MANY COMMON ETTORS SO 
*M2 O 

MANY COMMON ERRORS SO 
*NP 2 O 

THE MACRO CONNANDS CAN 
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*M1 ® 

THE MACRO COMMANDS CAN 

*M2 ® 

WITH AN ERROR; AND THEN, THE 

* [RET] <D 

MACRO EXECUTE CONNAND 

*M1 ® 

MACRO EXECUTE COMMAND 

*M2 ® 

IS ISSUED TO CORRECT THE 

*M2 (D 

ERROR 

*T ® 

*LI ® 

THIS LITTLE FILE HAS 

MANY COMMON ERRORS SO 

WE CAN SHOW YOU HOW 

THE MACRO COMMANDS CAN 

BE USED. 

FIRST, THE DESIRED MACRO 

MUST BE DEFINED; THE LINE 

POINTER IS MOVED TO A LINE 

WITH AN ERROR; AND THEN, THE 

MACRO EXECUTE COMMAND 

IS ISSUED TO CORRECT THE 

ERROR. 

[*EOB*] 

*EX ® 

Notes for Macro Commands Example 
O EDI opens file START.DAT. 

e The LI command (Ust on Terminal) displays the contents of the file and reveals any errors. 
The following errors are located: 

The string NN is used in place of MM (see macro 1). 
The string TT is used in place of RR (see macro 2). 
The string YHE is used in place of THE (see macro 3). 

O Three Macro commands define the macros that will correct the errors. 

O The M3 command (Macro Execute) changes all YHE strings to THE. 

© The NP command (Next & Print) locates a line with errors. 

O The Ml command (Macro Execute) changes NN to MM. 

O The M2 command (Macro Execute) changes TT to RR. 

© The NP command (Next & Locate) locates the next line in error. 

© The Ml command (Macro Execute) changes NN to MM. 

® The M2 command (Macro Execute) locates the next TT string and changes it to RR. 

® Pressing the RETURN key locates the next line in error. 

® The Ml command (Macro Execute) changes NN to MM. 
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® The M2 command (Macro Execute) locates the next TT string and changes it to RR. 

® The M2 command (Macro Execute) locates the last error in the file and corrects it. 

® The T command (Top) moves the line pointer to the top of the file. 

® The LI command (List on Terminal) displays the contents of the file. 

® The EX command (Exit) closes the file and terminates the editing session. 

7.1 1 EDI Messages 

The four classes of EDI error messages are as follows: 

• Command level information messages 

• File access error messages 

• Error messages requiring EDI restart 

• Fatal error messages 

The following sections describe all the messages that can be displayed in each class. If the 
recovery procedure is not evident, a suggested user action is given. 

7.11.1 EDI Command Level Informational Messages 

Messages in the command level information class display information that is designed to be 
helpful to you or to identify errors that were encountered in the previous command. AU 
messages in this class are enclosed within square brackets and are followed by the asterisk 
prompt ( • ) for a new command. 

The messages in this class are as follows: 
[BUFFER CAPACITY EXCEEDED BY] 

<o(rendlng line> 
[LINE DELETED] 

Explanation: A Read, Unsave, Insert, or Overlay command has exceeded the capacity of the 
block buffer. The line that caused the overflow is displayed and deleted. 

User Action: If a new file is being created, empty the buffer with a Write command and 
continue the editing session. 

If an existing file is being edited, it may be possible to continue by using a Renew or Write 
command. Otherwise, use the Close command to dose the output file and save all edits. 
Reopen the output file as the input file and, using the Size command, reduce the number of 
lines read into each buffer. Then, using the Page Locate command, search to the position 
in the file where editing is to continue. Occasionally, this message results when you try 
to open a file that was not created by EDI. You can overcome this difficulty by using the 
following command procedure: 

1. Type KILL. 

2. Enter a nonexistent file name when EDI prompts for a new file specification. EDI creates 
a new file and enters input mode. 

3. Press the RETURN key to enter edit mode. 
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4. Reduce the number of lines read into each buffer by using the Size command. 

5. Use the Kill command to abandon the file. 

6. Enter the name of the desired file when EDI prompts for a new file specification. 

[CREATING NEW FILE] 
Input 

Explanation: The input file specified with the command does not exist and EDI has created 
a new file. EDI automatically enters input mode and waits for the input of text lines. 

User Action: If you intend to create a new file, continue entering new lines as required. 
Otherwise, enter edit mode by pressing the RETURN key and use the Kill command to delete 
the undesired new file. When EDI prompts for a new file specification, enter the correct file 
specification. 

[ILL CMD] 

Explanation: Either EDI does not recognize the command or you have entered a command 
that is not compatible with the current mode (for example, a Read command in line-by-line 
mode). 

User Action: Reenter the correct command line. 

[ILL NUM] 

Explanation: Either you have supplied a nonnumeric character when a numeric character is 
required, or you have given a negative number when a positive number is required. 

User Action: Reenter the correct command line. 

[ILL STRING CONST] 

Explanation: A search string specified in a Change, Line Change, Paste, or Search & 
Change command does not contain a matching string termination character (for example, PA 
/ALPHABETA, instead of PA /ALPHA/BETA). 

User Action: Reenter the correct command line. 

[ILLEGAL IN BLOCK ON MODE] 

Explanation: You have tried to execute a command that is illegal in block mode, such as 
File or Output On/Off. 

User Action: Reenter the correct command line. 
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[ILLEGAL FILE NAME GIVEN IN CLOSE OR EXIT] 
or 

[FILE WAS NOT RENAMED] 

Explanation: A syntactically incorrect file specification was given in a Qose or Exit command, 
the attempt to rename the output file failed, or the attempt to exit or close to rename the 
file to another device failed. 

User Action: Use the PIP switch /RE or the DCL command RENAME to rename the file, if 
desired. 

[MACRO NOT DEFINED] 

Explanation: You have tried to execute a macro with the M command, but the specified 
macro has not been defined. 

User Action: Use the Macro command to define the desired macro and then execute it with 
the M command. 

[MACRO NUMERIC ARG UNDEFINED] 

Explanation: You have tried to execute a macro without suppljdng a numeric argument. 
The macro definition contains a percent sign ( % ) character and thus demands a numeric 
argument. 

User Action: Specify the appropriate numeric argument and reenter the command line. 
[MCALL FILE DOES NOT EXIST] 

Explanation: You have issued an Macro Call command to retrieve a set of macros, but the 
file MCALL cannot be found. 

User Action: The desired set of macro definitions may exist under another directory. If this 
is the case, use PIP or the appropriate DCL commands to copy or rename the MCALL file 
into the current directory. 

[NO INPUT FILE OPEN] 

Explanation: You have issued a Page, Read, or Renew command while a new fUe is being 
created (that is, while there is no input file). These commands can be executed only when 
an existing file is being edited. 

User Action: Open the input file and reenter the command line. 
[NO MATCH] 

Explanation: You have issued a Change command with a string to be changed that is not in 
the current line. 

User Action: Specify another string and reenter the command line. 
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[OVERLAYING PREVIOUSLY DEFINED MACRO] 

Explanation: You have issued a Macro command that redefines a previously defined macro. 
This message lets you know that the previous definition is no longer in effect. 

User Action: This message is for your information. No user action is required. 

[SAVE FILE DOES NOT EXIST] 

Explanation: The file specified in an Unsave command cannot be located. 

User Action: If you provided a file specification, make sure it is correct. If you did not 
provide a file specification, this message means that no previous Save command (without 
file specification) was issued. 

[SECONDARY FILE ALREADY OPEN] 

Explanation: You may have tried to open a secondary input file while another secondary 
file is still open. Or you may have a secondary file open when you issue a Close or Kill 
command, or when EDI encounters an error and is forced to restart. The former case 
represents an error. The latter informs you that you still have a secondary file open. 

User Action: Close the secondary input file by using the Close Secondary command and 
then open the desired secondary file with the Open Secondary command. 

[SECONDARY FILE CURRENTLY SELECTED FOR INPUT] 

Explanation: You have issued a Close or Kill command, or an error has caused EDI to restart 
when a secondary input file is open and selected for input. 

User Action: Issue a Select Primary command and a Close Secondary command. 

[SYNTAX ERROR] 

Explanation: You entered a command that is syntactically incorrect. 
User Action: Reenter the correct command line. 

[TOO MANY CHARS] 

Explanation: A Change, Line Change, Paste, Search & Change, or Add command has 
resulted in a line that contains too many characters. EDI limits the length of a line to 
132io characters. 

User Action: Reenter the correct command line. 

[•BOB-] 

Explanation: You have reached the beginning-of-buffer. The current line pointer is positioned 
just before the first line in the buffer. Thus, new text lines can be entered before the first 
line. 

User Action: This message is for your information. No user action is required. 
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[•EOB-] 

Explanation: You have reached the end-of-buffer. The current line pointer now points to 
the end of the buffer. Thus, if new lines are inserted, they appear after the last text in the 
buffer. 

User Action: This message is for your information. No user action is required. 

[•EOF-] 

Explanation: You have reached the end-of-file on the input file. 

User Action: If the editing session is complete, use the Close or Exit command to close the 
output file. Otherwise, use the TOF command to return to the first block in the file. 

7.n.2 EDI File Access Error Messages 

Error messages in the file access class mean that you have tried to access directories, files, or 
devices that are not present in the host system. 

The format of the error messages is as follows: 

EDI — message 

After the message is displayed, EDI returns to command level and prints the asterisk ( * ) prompt 
to request input. 

The messages in this class are as follows: 

EDI— BAD FILE NAME 

Explanation: EDI did not accept the file name. 

User Action: Ensure that the file name is correct and then reenter it. 

EDI— DEVICE NOT IN SYSTEM 

Explanation: You have given a File, Open Secondary, Save, or Unsave command and have 
specified a device that does not exist in the host system. 

User Action: Specify a device available in the system and reenter the command line. 
EDI— FILE DOES NOT EXIST 

Explanation: You have given a File or Save command and have specified a directory that 
does not exist on the specified volume. 

User Action: Specify the correct file specification and reenter the command line. 

Note 

The remaining error messages in this class should not occur and represent 
failures in EDI. If such errors persist, submit a Software Performance Report 
(SPR). 

EDI— BAD DEVICE NAME 

EDI— DEVICE NOT READY 
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EDI— FILE ALREADY OPEN 
EDI— RENAME NAME ALREADY IN USE 
EDI— RENAME ON TWO DIFFERENT DEVICES 
EDI— WRITE AHEMPT TO LOCKED UNIT 

7.1 1.3 EDI Error Messages Requiring Restart 

The error messages described in this section are caused by conditions that make it impossible 
for EDI to continue the current editing session. EDI closes all open files (with the exception of 
any open secondary input file), reinitializes, and then prompts for the next file to be edited. 

The format of the error messages is as follows: 

EDI ~ message 

After the appropriate message has been displayed, EDI prompts with the following: 

EDI> 

You may terminate the editing session at this point by pressing the RETURN key or CTRL/Z, or 
you may continue by entering another file specification. If a secondary file was open when the 
error condition was encountered, it remains open. 

The messages in this class are as follows: 

EDI— BAD RECORD TYPE— FILE NO LONGER USABLE 

Explanation: The record type defined in the header block of the input file (primary input, 
secondary input, UNSAVE, or MCALL) is not supported by the File Control Services (FCS). 
Thus, the file cannot be used for input to EDI. 

User Action: The referenced file has been created without using FCS or the file structure 
on the volume is damaged. In the latter case, verify the file structure with the File 
Verification Structure Utility (VFY) to determine the extent of the damage. VFY is described 
in Chapter 14. 

EDI— FILE ACCESSED FOR WRITE 

Explanation: The input file (primary input, secondary input, UNSAVE, or MCALL) is 
currently being written by another task. 

User Action: Wait for the write to complete and then reenter the command line. 

EDI— FILE IS LOCKED TO WRITE ACCESS 

Explanation: The output file (text output, FILE, or SAVE) is currently accessed for read by 
one or more tasks and is locked against all writers. 

User Action: Wait for all reads of the file to finish and then reenter the command line. 
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EDI— ILLEGAL RECORD AHRIBUTES— FILE NOT USABLE 

Explanation: The record attributes defined m the header block of the input file (primary 
input, secondary input, UNSAVE, or MCALL) are not supported by FCS. Thus, the file 
cannot be used for input to EDI. 

User Action: The referenced file has been created without using FCS or the file structure on 
the volume is damaged. In the latter case, run VFY to detemune the extent of the damage. 
VFY is described in Chapter 14. 

EDI— PRIMARY FILE NOT PROPERLY CLOSED— NOT USABLE 

Explanation: When the primary input file was last written, a close check was specified and 
the writing task did not properly close the file (for example, the task was aborted). Thus, 
the file attributes were not written and the file may contain inconsistent data. 

User Action: Exit from EDI by pressing the RETURN key or CTRL/Z. Use the PIP switch /UN 
to unlock the file. Reinitiate EDI and try to recover the data in the file. 

EDI— PRIVILEGE VIOLATION 

Explanation: A privilege violation occurred during a file access for one of the following 
reasons: 

• The specified volume was not mounted. 

• The User Identification Code (UIC) under which EDI was running did not possess the 
necessary privileges to access the specified directory. 

• The UIC was not privileged to access the specified file. 

User Action: If the volume is not mounted, then mount it by using the MOUNT command. 
Otherwise, reinitiate EDI under a UIC that has appropriate access privileges to both the 
specified directory and file. 

EDI— RECORD IS TOO LARGE FOR USER BUFFER 

Explanation: The input file (primary input, secondary input, UNSAVE, or MCALL) being 
accessed was not created by EDI (or SLP) and contains records that are too large. The 
maximum record length supported by EDI is 132io bytes. 

EDI— SECONDARY FILE NOT PROPERLY CLOSED— NOT USABLE 

Explanation: When the secondary input file was last written, a close check was specified and 
the writing task did not properly close the file (for example, the task was aborted). Thus, 
the file attributes were not written and the file may contain inconsistent data. 

User Action: Use the PIP switch /UN to unlock the file. Reinitiate EDI and try to recover 
the data in the file. 
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EDI— BAD DIRECTORY SYNTAX 

Explanation: The directory field ([directory]) is in improper format. 

User Action: Specify the directory in the correct format and reenter the command line. 

Note 

The remaining error messages in this class should not occur and represent 
failures in EDI. If such errors persist, submit an SPR. 

EDI— DUPLICATE ENTRY IN DIRECTORY 

EDI— END OF FILE 

EDI— ILLEGAL RECORD ACCESS BITS— FILE NOT USABLE 

EDI— ILLEGAL RECORD NUMBER— FILE NOT USABLE 

7.1 1.4 EDI Fatal Error Messages 

The fatal error messages represent system and/or hardware conditions that make it impossible 
for EDI to continue execution. All files are closed and EDI terminates its execution. The output 
file may be truncated. Each error message is prefixed with the following: 

EDI — 

The error message is then followed by the exit message on the next line as follows: 
[EXIT] 

You may use the following procedure on the truncated version of an output file to save the 
editing performed before the fatal error occurred: 

1. Use the PIP switch /RE or the DCL command RENAME to rename the truncated version 
of the output file to avoid confusion. 

2. Restart the editing session to the original input file. 

3. Issue the Open Secondary command, and specify the renamed file as the secondary file. 

4. Issue the Select Secondary command to select the secondary file for input. 

5. Issue the Erase command to erase the first block of the input file (unless the truncated 
output file did not contain the entire first block). 

6. Issue as many Read and Write commands as necessary to reach the EOF on the secondary 
file. 

7. Issue the Select Primary command to select the primary file for input. 

8. Issue the Close Secondary command to close the secondary file. 

9. Issue the Write command to ensure that the last block was written into the output file. 

10. Issue as many Read and Erase commands as necessary to bypass all input file blocks that 
are complete in the renamed file. 

11. Continue with the normal editing session. 
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The messages in this class are as follows: 

EDI— CALLER'S NODE EXHAUSTED 

Explanation: System dynamic storage has been depleted and insufficient space is available 
to allocate the control blocks necessary to open, close, read, or write a file. 

User Action: This probably is a system failure, but it could also represent a transient overload 
condition. Wait until system load has diminished and reinitiate EDI. 

EDI— DEVICE FULL 

Explanation: Insufficient space exists on the output volume to extend an output file (text 
output, FILE, or SAVE). 

User Action: Determine which volume is being written to. If it is required that the specified 
file be written on this volume, then space must be made available. Use PIP to purge or 
delete unwanted files, or use the DCL commands PURGE and DELETE. 

EDI— FILE HEADER CHECKSUM ERROR 

Explanation: An input file (primary input, secondary input, UNSAVE, or MCALL) has a 
header block that does not contain a proper checksum. 

User Action: The file structure on the specified volume is damaged. Run VFY to determine 
the extent of the damage. VFY is described in Chapter 14. 

EDI— FILE HEADER FULL 

Explanation: Insufficient retrieval pointer space exists in the header block to extend an output 
file (text output. File, or Save). 

User Action: Split the file into two or more files and process them separately. 

EDI— FILE PROCESSOR DEVICE WRITE ERROR 

Explanation: This error message may indicate that the. device specified for an output file is 
write-locked. 

User Action: Unlock the device if it is write-locked. Otherwise, a hardware problem may 
exist. Consult your DIGITAL Field Service representative. 

EDI— INDEX FILE FULL 

Explanation: The file header block is not available to create an output file (text output, FILE, 
or SAVE). When a volume is initialized, the maximum number of files that may be created 
on the volume is established. Your write request exceeded this linut. 

User Action: Determine which volume is being referenced. If it is required that the specified 
file be created on this volume, then space must be made available. Use PIP to purge or 
delete unwanted files, or use the DCL commands PURGE or DELETE. 
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EDI— BAD BUFFER ADDRESS OR HANDLER NOT LOADED 

Explanation: The device driver may not be loaded in the system, or an internal error has 
occurred. 

User Action: If the device driver is not loaded, load the device driver and configure the 
device into the system. If the device driver was loaded, contact your DIGITAL Field Service 
representative. 

Note 

The following error messages signify hardware problems. If possible, remove 
all important files from the volume, and contact your DIGITAL Field Service 
representative. 

EDI— BAD BLOCK ON DEVICE 

EDI— FILE PROCESSOR DEVICE READ ERROR 

EDI— HARDWARE ERROR ON DEVICE 

EDI— PARITY ERROR ON DEVICE 

Note 

The remaining error messages in this class should not occur and represent 
failures in EDI. If such a failure occurs, contact your DIGITAL Field Service 
representative. 

EDI— BAD DIRECTORY FILE 

EDI— BAD PARAMETERS ON A QIO 

EDI— INVALID FUNCTION CODE ON A QIO 

EDI— NO BLOCKS LEFT 

EDI— REQUEST TERMINATED 

EDI— UNEXPECTED ERROR— EDITOR WILL ABORT 

EDI— WRITE AHRIBUTE DATA FORMAT ERROR 

TASK "...EDI" TERMINATED 
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Chapter 8 

File Transfer Program (FLX) 



The File Transfer Utility Program (FLX) allows you to use foreign volumes (not in Files- 11 
format) in DIGITAL'S DOS-11 or RT-11 format. FLX converts the format of a file to the format 
of the volume the file is being transferred to. 

FLX can be used to initialize and list directories of cassettes and RT-11 or DOS-11 file-structured 
volumes. FLX can also be used to delete files from RT-11 or DOS-11 formatted volumes. 

FLX performs file transfers (and format conversions, as appropriate) as follows: 

DOS-11 to Files-11 volumes 

Files-11 to DOS-11 volumes 

DOS-11 to DOS-11 volumes 

Files-11 to Files-11 volumes 

Files-11 to RT-11 volumes 

RT-11 to RT-11 volumes 

RT-11 to Files-11 volumes 
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Valid DOS-11 devices are as follows: 



Device 



Abbreviation 



PCll paper tape punch PP 

PCll and PRll paper tape readers PR 

RK05 cartridge disk DK 

TE16, TU16, TU45, and TU77 magnetic MM 
tapes 

TS04, TSll, TSV05, and TU80 magnetic MS 
tapes 

TUlO and TS03 magnetic tapes MT 

TU56 DECtape DT 

TU60 tape cassette CT 

TK50 and TU81 magnetic tape drive MU 



Valid RT-11 devices are as foUov^rs: 



Device 



Abbreviation 



RL01/RL02 cartridge DL 

RK05 cartridge disk DK 

RK06 and RK07 cartridge disks DM 

RXOl diskette DX 

RX02 diskette DY 

RX33 and RX50 diskettes DU 

RD31, RD32, RD51, and RD52 disks DU 

RC25 and RCF25 fixed/removable disks DU 

TU56 DECtape DT 

TU58 DECtape II data cartridge DD 



FLX supports all Files-11 devices, including RSX-format cassettes. The cassettes are volumes 
that you have initialized using the Monitor Console Routine (MCR) command INITVOL or 
Digital Command Language (DCL) command INITIALIZE. DOS-11 and RT-11 volumes are 
initialized using FLX. On RSX-llM-PLUS operating systems, DOS-11 and RT-11 volumes 
must be mounted with foreign characteristics before you can use FLX. 

You can use FLX interactively or by means of an indirect commmand file. FLX allows only one 
level of indirect command file specification. 
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8. 1 FLX Command Line 

You can invoke FLX by any of the methods described in Chapter 1. Although formats for 
specifying FLX functions vary, the general format for entering FLX command lines is shown 
next. 

Format 

[ddnn:[[directory]]/switch[...]=]infae[,...]/switch[...] 

Parameters 
ddnn 

Specifies the device for the FLX output. 

directory 

Specifies the directory on the output device. 

The [directory] field is optional; if it is not specified, FLX uses the current default directory. 
Do not specify a directory if the output device is in RT-11 format. 

switch 

Specifies one of the FLX switches described in Section 8.1.1. 

Inflle 

Specifies the input file specification. 

The format for entering file specifications is as follows: 

ddnn : [directory] filename . type ; version 

Refer to Chapter 1 for detailed descriptions of the parameters for file specifications. 

The directory is not specified for RT-1 1 volumes. 

If you explicitly enter the output device specification, you must enter the equal sign (=). 

FLX does not permit output file specifications. The output files take the names of the input files. 

FLX supports 9-character file names for DOS-ll-format magnetic tapes. When you ti-ansfer the 
file back to Files-11 format (which uses a 12-character file name), FLX will recover the last 
three characters. 

Wildcards are valid only for input file specifications. 

Version numbers are valid only for Files-11 files and cannot be specified as wildcards. The 
standard rules for updating version numbers apply (see the RSX-llM-PLUS MCR Operations 
Manual). 
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8.1.1 FLX Switch Descriptions 

FLX provides three types of switches for file transfers: 

Volume format switches Specify the format of the volume on which files are stored; that is, 

Files-11, DOS-11, or RT-11 volumes. 

Transfer mode switches Provide the means for specifying the format of a file on a 

non-Files- 11 volume. Files can be in formatted American Standard 
Code for Information Interchange (ASCII), formatted binary, or file 
image format. 

Control switches Provide control functions useful during file transfers. Using file control 

switches, you can specify, for example, the number of blocks to be 
allocated to an output file or the directory for an output file. 

The following switches accept octal numbers by default: 

/FA[:n] 

/FB[:n] 

/IM[:n] 

/BL:n 

/BS:n 

/NU:n 

/ZE[:n] 

[f you want to assign decimal numbers to these switches, you must follow the value of n with 
period ( . ). In order to assign the decimal value to the /IM[:n] switch, type the following: 

IM:18. 

The /DNS switch accepts decimal numbers by default. Therefore, you do not need to follow 
the value of the /DNS switch with a period ( . ) if the value is decimal. 

8.1.1.1 Volume Format 

FLX has three volume format switches, as described in Table 8-1, that define the format of the 
specified volumes. 

Table 8- 1 : FLX Volume Format Switches 



Switch Description 



/DO Identifies the volume as a DOS-11 formatted volume. 

/RS Identifies the volume as a Files-11 formatted volume. 

/RT Identifies the volume as an RT-11 formatted volume. 



Initially, input volumes default to DOS-11 format and output volumes default to Files-11 format. 
FLX assumes these default volume formats if you do not specify switches in the command line. 
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You can change the initial defauh by entering the /RS or /DO switch on a command line by 
itself. The /RS switch sets the default for input volumes to Files- 11 format and output volumes 
to DOS-11 format. The /DO switch sets the default for input volumes to DOS-11 format and 
output volumes to Files- 11 format. 

If the /RT switch is specified on one side of a command line, the default entry for the other 
side is the /RS switch. 

Examples 

FLX>/RS \M] 

Specifies the default transfer direction from Files-11 to DOS-11. 

FLX>/DO [RET] 

Specifies the default transfer direction from DOS-11 to Files-11. 
FLX>DK0:=DT0:SYS1.MAC/RT [RET] 
Defaults the output to the /RS switch. 
FLX>DKO : /RT=DKO : S YS 1 . MAC \Mi 
Defaults the input to the /RS switch. 

8.1.1.2 Transfer Mode 

FLX has three transfer mode switches— one for each type of file format. Files can be in formatted 
ASCII, formatted binary, or file image format. Format conversions can be in either direction, 
and they are between DOS-11 files and Files-11 files or between RT-11 files and Files-11 files. 
Specifying a transfer mode switch determines which format the output file will be in after the 
conversion of the file. Table 8-2 describes the transfer mode switches. 
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Table 8-2: FLX Transfer Mode Switches 



Switch 



Format Function 



Formatted ASCII /FA[:n] The DOS-11 or RT-11 output file is to be formatted ASCII. 

Formatted ASCII is defined as ASCII data records terminated by 
a carriage-retum/Iine-feed combination (RET-LF), form feed (FF), 
or vertical tab (VT). In transfers from DOS-11 or RT-11 files to 
Files-11 files, RET-LF pairs are removed from the end of records. 
In transfers from Files-11 files to DOS-11 or RT-11 files, RET-LF 
pairs are added to the end of each record that does not already end 
with LF or FF. In both directions, all nulls, rubouts, and vertical 
tabs are removed from input records. 

If you specify /FA:n with Files-11 output, fixed-length records of 
size n are generated. Output records are padded with nulls, if 
necessary. 

If you do not specify n with Files-11 output, FLX generates variable- 
length records. The output record size equals the input record size. 

ASCII data is transferred as 7-bit values. Bit 8 of each byte is 
masked off before transfer. Pressing CTRL/Z (ASCII OSZg) is treated 
as the logical end-of-input file for formatted ASCII transfers from 
DOS-11 cassette or paper tape to Files-11. 

Formatted Binary /FB[:n] The DOS-11 or RT-11 output file is to be formatted binary. In 

this mode, formatted binary headers and checksums are added to 
records that are output to DOS-11 or RT-11 files, and they are 
removed when transferred to Files-11 files. 

If you specify /FB:n with Files-11 output, fixed-length records of 
size n are output (512io bytes is the maximum). FLX pads records 
with nulls to create the specified length. 

If you do not specify n with Files-11 output, FLX generates variable- 
length records. The output record size equals the input record size. 

Image Mode /IM[:n] The transfer is to be in image mode. Image mode forces fixed- 

length records. You can use the value n to indicate the desired 
record length (in decimal bytes) for Files-11 output (512io bytes 
maximum). If you do not specify n, FLX assumes a record length 
of 512io bytes. 



FLX assumes the following default transfer modes for these file types (with the exception of 
paper tape transfers described in Section 8.5): 



Mode 



Switch File Type 



Image /IM[:n] 

Formatted Binary /FB[:n] 
Formatted ASCII /FA[:n] 



TSK, OLB, MLB, SYS, SML, ULB, EXE, CDA 
OBJ, STB, BIN, LDA 
All others 
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If you specify n with the /FA, /FB, or /IM switch when the output file is not a Files-11 file, 
FLX ignores n. 

See the RSX-UM-PLUS MCR Operations Manual, RSX-llM-PLUS Command Language Manual, 
and RSX-UM-PLUS Guide to Program Development for definitions of the file types listed above. 

8.1.1.3 Control 

FLX provides a number of control switches to control file processing. Table 8-3 describes these 
switches. 

Table 8-3: FLX Control Switcties 



Switch Format Function 



/BL:n Indicates the number of contiguous blocks (n) in octal or decimal to be allocated 

to the output file. 

This switch is normally used with the /CO switch (described later in this table). 
Because all RT-11 files are contiguous, the /CO switch is not required with the 
/BL switch for RT-11 output. 

If you do not specify the /BL switch, the input file size is used as the output 
file size. 

The file allocation scheme used for RT-11 volumes normally allocates the largest 
available space on the volume for a new file. Using the /BL switch with the 
/RT switch for the output file causes the output file to be allocated the first 
unused space of size n. However, when the RT-11 file is closed, the input file 
size is used as the output file size. If the input file is not n, an error results. 

/BS:n Specifies the block size n in decimal bytes for cassette tape (CT) output. 

If you do not specify the /BS switch, a block size of 128io is assumed. The 
/BS switch is only valid in a CT output file specification with the /RS switch 
specified. 

/CO Indicates that the output file is to be contiguous. The /CO switch is used only 

with disks and DECtapes. 

If the input file is on paper tape, cassette, or DOS-11 magnetic tape, the /BL 
switch is also required. FLX transfers the file types TSK, SYS, and OLB to 
Files-11 volumes with the /CO switch implied when the input is a FiIes-11 
volume or a DOS-11 or RT-11 DECtape or disk. 

/DE Deletes fUes from a DOS-11 DECtape or disk. It is used also with the /RT 

switch to delete files from an RT-11 DECtape or disk. When you specify the 
/DE switch, the FLX command line has no output specification. 
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Table 8-3 (Cont.): FLX Control Switches 



Switch Format Function 



/DI Causes a directory listing of cassettes or DOS-11 volumes to be listed on a 

specified output file. It is used also with the /RT switch to generate a directory 
listing of RT-11 volumes in a specified output file. 
You cannot list Files-11 volume directories by using FLX. 
If you do not specify an output device, the directory is sent to TI. If you do 
not specify file name and file type on the input file specification, a wildcard is 
assumed. 

See Section 8.2 for information on DOS-11 volume directory manipulation. See 
Section 8.3 for information on RT-11 volume directory manipulation. 

/DNS:n Specifies the density of the magnetic tape, where n is 800 or 1600 bpi. If n is 

any other value or is not specified, FLX prints an error message. If you do not 
specify the /DNS switch, the magnetic tape density defaults 1600 bpi for the 
TSll and 800 bpi for all other magnetic tape devices. If you specify the /DNS 
switch with a nonmagnetic device, FLX ignores the switch. 

/FC Indicates, when using FORTRAN files, that FORTRAN carriage control conven- 

tions are to be used. The /FC switch applies only to Files-11 output files. If 
you have the PDP-11 FORTRAN Language Reference Manual, refer to it for more 
information on FORTRAN carriage control conventions. Otherwise, refer to the 
RSX-llM-PLUS and Micro/RSX I/O Operations Reference Manual for a discussion 
of the file data block and record attributes, of which setting carriage control is 
a part. 

/ID Requests the current version number of FLX to be printed. You can specify the 

/ID switch as part of an output or input specification or type it in response to 
the FLX prompt (FLX> ). 

/LI Same as the /DI switch. 

/NU:n Used with the /ZE and /RT switches to specify the number of directory blocks 

n in octal or decimal to allocate when initializing an RT-11 disk or DECtape. 
If you do not specify the /NU switch, four directory blocks are allocated. The 
maximum number of blocks that can be allocated is 37^ or 31 lo- 

/RW Rewinds the magnetic tape before beginning the file transfer. Specifying the 

/-RW switch causes FLX to begin the transfer without first rewinding the 
magnetic tape. If you do not specify either rewind option, the switch defaults 
to the /RW switch. If you specify the /RW switch with a nonmagiietic tape 
device, or with the /LI, /DI, or /ZE switch; FLX ignores the /RW switch. 

/SP Indicates that the converted file is to be spooled by the print spooler task or 

the queue management system. The /SP switch applies only to Files-11 output 
files. 

/UI Indicates that the output file is to have the same directory as the input file. FLX 

ignores the /UI switch if the output specification contains an explicit directory. 
The /UI switch is valid only for output files in DOS-11 or Files-11 format. 
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Table 8-3 (Cont.): FLX Control Switches 



Switch Format Function 



/VE Causes each record written to a cassette to be read and verified. The /VE switch 

is only valid with a CT output file specification. 

/ZE[:n] Initializes cassettes or DOS-11 volumes. It is also used with the /RT switch 

and the /NU switch to initialize RT-11 volumes. Initializing erases any files 
already on the device. The /ZE switch does not allow a file specification. 

For DOS-11 DECtape, the /ZE switch creates an entry for the current User 
Identification Code (UIC). 

8.2 DOS-1 1 Volume Directory Manipulation 

This section contains examples that show how to display DOS-11 directory listings, delete 
DOS-11 files, and initialize DOS-11 volumes by using the FLX switches. 

DOS-11 volumes must be mounted with foreign characteristics before you can use FLX. 

8.2.1 Displaying DOS- n Directory Listings 

The /LI or /DI switch instructs FLX to send the directory of the cassette or DOS-11 volume 
specified in the input specification to the Files-11 file specified in the output specification. If 
you do not enter an output specification, FLX sends the directory to TI. 

Examples 

FLX>DTO :[ 100 , 100] * . MAC/LI [M] 

Lists on your terminal the directory of all MAC files under directory [100,100] on the DOS-11 
DECtape on DTO. 



PIP>DTO : [200 . 200] * . TSK/LI [M] 

Produces the following DOS-11 DECtape directory listing: 



O DIRECTORY 
© 19-SEP-86 


© 


DT: [200,200] 


© 




© FLX.TSK;! 
UFD.TSK;2 
TKN.TSK; 1 
M0U.TSK;7 




© 104. 
8. 
6. 
14. 


© 19-SEP- 
19-SEP-86 
19-SEP-86 
19-SEP-86 


86 <233> © 
<233> 
<233> 
<233> 



© Total of 132. blocks in 4. files 

PIP>CTO : [200 , 200] * . TSK/LI \M] 

Produces the following TU60 cassette directory listing: 

O DIRECTORY © CT: [200,200] © 
O 19-SEP-86 

© UFD.TSK-0 © 28. O 19-SEP-86 128. € 

TKN.TSK -0 20. 19-SEP-86 128. 

MOU.TSK-0 52. 19-SEP-86 128. 

© Total of 132. blocks in 4. files 
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Notes on examples: 

O Identifies the listing as a directory listing. 

® Specifies the device name and unit number. 

® Specifies the directory. 

© Specifies the date the directory was listed. 

© Specifies the file name, file type, and version number (DECtape only) or sequence number 
(cassettes only). 

® Specifies the file size in decimal blocks. 

© Specifies the file creation date. 

® Specifies the protection code provided by the system (DECtape only) or the record size in 
decimal bytes for the file (cassettes only). 

® Specifies the total actual file sizes and the total number of files in the directory. 

8.2.2 Deleting DOS- 11 Files 

You can delete files from DOS-1 1 disks or DECtapes by using the /DE switch. The /DE switch 
requires only the file specification for the file you are deleting. 

Example 

FLX>DK1:[100.100]SYS1.MAC/DE [RETI 

Deletes SYSl.MAC under directory [100,100] from the DOS-11 disk on DKl. 

8.2.3 initializing DOS-11 Volumes 

You can initialize cassettes and DOS-11 volumes by using the /ZE switch. This switch requires 
only the device specification for the volume you are initializing. 

Example 

FLX>DT1:/ZE \M\ 

Initializes the DECtape on DTI in DOS-11 format. 

8.3 RT-1 1 Volume Directory Manipulation 

You can display RT-11 directory listings, delete RT-11 files, and initialize RT-11 volumes by 
using the FLX switches described in this section. 

RT-11 volumes must be mounted with foreign characteristics before you can use FLX. 



8-10 File Transfer Program (FLX) 



8.3.1 Displaying RT- 1 1 Directory Listings 

The /LI or /DI switch, when combined with the /RT switch, instructs FLX to send the directory 
of the RT-11 volume in the input specification to the FUes-11 file in the output specification. If 
you do not enter an output specification, FLX sends the directory to TI. 

Example 

FLX>DTO:*.MAC/LI/RT [RET] 

Lists on your terminal all MAC files on the RT-11 volume on DTO. 

The follovnng example shows a sample directory listing for an RT-11 disk: 

O DIRECTORY @ DKl : 
O 4-JUN-87 



O SIPBOO.MAC 


O 49. 


© 4-JUK-87 


e < musm > 


6. 




SIP .MAC 


10. 


4-JUN-87 


SIPCD .MAC 


7. 


4-JUN-87 


< UNUSED > 


21. 




SIPQIO.MAC 


7. 


4-JUN-87 


< UNUSED > 


4686. 





© 4713. free blocks 

© Total of 73. blocks in 4. files 

Notes on example: 

O Identifies the listing as a directory listing. 

© Specifies the device name and unit number. 

© Specifies the date the directory was listed. 

O Specifies the file name and file t)T)e. 

© Specifies the number of blocks in the file or amount of free space. 

© Specifies the file creation date. 

© <UNUSED> specifies the amoimt of free space. 

® Specifies the total number of free blocks on the volume. 

© Specifies the total number of blocks allocated to files on the volume. 

8.3.2 Deleting RT-11 Files 

You can delete files from RT-11 disks or DECtapes by using the /DE switch with the /RT 
switch. The command line on which you specify /DE/RT requires only the file specification 
for the file you are deleting. 

Example 

FLX>DK1:SYS1.MAC/DE/RT [RET] 

Deletes SYSl.MAC from the RT-11 volume on DKl. 
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8.3.3 Initializing RT-ll Volumes 

You can initialize RT-ll volumes by using the /ZE switch with the /RT switch. The /ZE 
switch requires only the device specification for the volume you are initializing. 

Examples 

FLX>DT1 : /ZE/RT 

Initializes the DECtape on DTI in RT-ll format. When you initialize RT-ll volumes, the /ZE 
switch takes an optional argument in the following format: 

/ZE:n 

The value n specifies the number of extra words per directory entry. A directory segment 
consists of two disk blocks with a total of 512io words. The directory header uses five words, 
leaving 507io words for directory entries. 

Normally, each directory entry uses seven words; two directory entries within each directory 
segment are allocated to the file system. Therefore, the number of entries in each segment 
(when no extra words are specified) is determined as follows: 

Directory entries = (507/7) -2 

= 72-2 
= 70 

Some RT-ll applications require extra words in the directory entries. When you specify extra 
words for directory entries (using the /ZE switch), the number of directory entries is determined 
as follows: 

Directory entries = [507/(n+7)]-2 

For example, 61io entries can be made per directory segment if you specify /ZE:1. 

Use of the /NU svntch with the /ZE and /RT switches specifies the number of directory 
segments to allocate to the RT-ll volume. The /NU switch has the following form: 

/NU:n 

The value n specifies the number of directory segments to allocate. Four directory segments are 
allocated by default. The maximum number of segments that can be allocated is SZg or 31io. 

FLX>DT0:/ZE:2/NU:6/RT Wf] 

Initializes the DECtape on DTO in RT-ll format, allocates two extra words per directory entry, 
and allocates six directory segments. This results in a total of 324io directory entries, each of 
which uses nine words. 
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8.4 FLX TAl 1/TU60 Cassette Support 

FLX supports the DIGITAL standard cassette file structure. Files can be transferred to and from 
cassettes in either Files-11 format (using the /RS switch) or DOS-11 format (using the /DO 
switch). The transfer mode selected depends on the file format requirements. 

The file formats for Files-11 or DOS-11 cassette files are almost the same; that is, they both 
conform to the DIGITAL standard cassette file format. The differences between the FUes-11 
and DOS-11 cassette file formats are shown in Table 8-4. 

Table 8-4: Differences Between Files- 1 1 and DOS- 11 Cassette Files Format 

Files-11 Format DOS-11 Formal 

Standard level 2 Standard level 

9-character file name and 3-character file 6-character file name and 3-character file type 
type 

Blocks of any size up to 512io bytes 128io-byte blocks 

128io bytes default 

Version numbers No version numbers 

Files-11 cassette file format (level 2) is a superset of the DOS-11 cassette file format (level 0). 
Therefore, any cassette written in DOS-11 format can be read in Files-11 format. The reverse 
of this, however, is true only when the following occur: 

• The Files-11 file is written with 128io-byte blocks. 

• The extra file header data (such as version number), which does not appear in DOS-11 
files, can be ignored. 

Files-11 files and DOS-11 files can be mixed on a given cassette as long as you use a proper 
retrieval mode when you access the file. Files of various block sizes can also share a given 
cassette. FLX uses the block size contained in the file label data when reading a file. 

8.4.1 Multivolume Cassette Support 

FLX supports multivolume cassette files in both Files-11 and DOS-11 formats. No special 
switches are required to notify FLX that a multivolume file is being accessed. 

8.4.2 FLX Cassette Output Files 

When FLX detects the physical end-of-tape for an output cassette, the following sequence of 
events occurs: 

1. FLX issues the following message: 

FLX — End of Tolume on cassette 
CTn : [directory] 

The variable n specifies the unit number. 

2. The cassette rewinds. 
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3. FLX issues an additional message as follows: 

Mount new cassette? (Y, Z (output only) or CR) 
FLX> 

4. FLX provides you with the following three alternatives: 

a. Mount the next output cassette volume, press the Y key, and then press the RETURN 
key. If you select this alternative, the new output cassette rewinds, FLX searches for 
the logical end-of-tape (end of the last file), and then continues transferring data onto 
the tape. If FLX, while searching for the logical end-of-tape, encounters a file with the 
same file name as the current input file, it displays the following message: 

FLX — File already exists 

FLX then returns to step 3. 

b. Mount the next output cassette volume, press the Z key, and then press the RETURN 
key. The new output cassette rewinds, and FLX continues by transferring data onto it. 
Thus, the tape is effectively zeroed (initialized) before data is transferred to it. 

c. Press the RETURN key to terminate the transfer. 

If you select this alternative, FLX assumes that end-of-file (EOF) is desired, and it issues 
the following message: 

FLX — Request terminated — Last block not written 

This message indicates that the last input file block processed was not written onto the 
tape. 

8.4.3 FLX Cassette Input Files 

When FLX detects the physical end-of-tape for an input cassette, the following sequence of 
events occurs: 

1. FLX issues the following message, including the input file specification on which the end- 
of-tape was detected: 

FLX — End of volume on cassette 
CTn: [directory] filename. type 

The variable n specifies the unit number. 

2. The cassette rewinds. 

3. FLX issues an additional message, as follows: 

Mount new cassette: (Y, Z (output only) or CR) 
FLX> 

4. FLX provides you with the following two alternatives: 

a. Mount the next input cassette volume, press the Y key, and then press the RETURN key 
to continue. If you select this alternative, the new input cassette is rewound, and a 
validity check is performed on the file label and sequence number. If the file label and 
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sequence number are correct, FLX begins processing data from the volume. If, however, 
the file label and sequence number are not correct, FLX issues the following message: 

FLX -- File not found 

FLX then returns to step 3. 

b. Press the RETURN key to terminate the transfer. If you select this alternative, FLX 
assumes that end-of-file (EOF) is desired, and the transfer is terminated. If the input 
file is being processed as a formatted binary or an ASCII file, a format error may occur. 

If you press the Z key, FLX prints the following message: 

FLX — Bad response 

FLX then returns to step 3. 

8.5 FLX Paper Tape Support 

FLX supports the DIGITAL standard paper tape devices, such as the PC- 11 paper tape reader 
/punch and the PR- 11 paper tape reader, as DOS- 11 devices. 

FLX lets you delimit records on paper tape for files in formatted binary mode or in formatted 
ASCII mode. Formatted binary records are delimited by standard DOS-11 4-byte headers and 
a trailing checksum. Formatted ASCII records that do not already end with line feeds or form 
feeds are delimited by carriage-retum/line-feed combination pairs. 

FLX gives special treatment to files that normally default to image mode transfers; that is, TSK, 
OLB, MLB, SYS, SML, EXE, and ULB files. On output to paper tape, these files are written, by 
default, in formatted binary. When read back from paper tape to a Files-11 volume, the file is 
written by default, with fixed-length, 512io-byte records. 

These defaults ensure that when the files are read back from paper tape they are in the same 
format as they were before being punched. However, the new files are not contiguous unless 
you specify /CO/BL:n with the output file specification. You must know an appropriate value 
for n (the number of contiguous blocks to allocate) before issuing the command. You can also 
use PIP to create a contiguous file from the file that is read back from tape (see Chapter 12). 

The use of explicit transfer mode switches to transfer TSK, OLB, MLB, SYS, SML, EXE, and 
ULB files between paper tape and Files-11 volumes can cause files read back from paper tape 
to be different from the files that were originally written out. 

For FLX paper tape transfer commands, you cannot specify file names in the output specification. 
The file name entered for the input file specification is used as the file name for the output file. 

If you do not specify a file name on the input file specification, the default file name is ".;n" 
where n represents the latest version number. 

The RSX-llM-PLUS operating system supports paper tapes only as DOS-11 devices. Therefore, 
you must specify the /DO switch with paper tape file specifications. 

Examples 

FLX>DK 1 : /RS=PR : CRTMAC .DAT/DO [RETI 

Writes an output file whose file name is DK1:CRTMAC.DAT. 
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FLX>PP : /DO -CRTMAC . DAT/RS (RETI 
FLX>DK : /RS=PR : CRTMAC . DAT/DO 



Shows paper tape specifications for input and output fQe specifications. 

FLX>PP:/DO/IM=PR:/DO \M] 

Copies from one paper tape to another by using the Image Mode switch (/IM), regardless of 
the format of the paper tapes. 

8.6 FORTRAN Direct Access Files 

FORTRAN direct access files must be transferred in image mode. 
Examples 

FLX>DKO : /D0/IM=FOO . TJP/RS [RET] 

Transfers the file FOO.TJP without specifying the record length. 

FLX>/RS/IM:18.=DKO:FO0.TJP/D0 [RET] 

Transfers the file FOO.TJP with the record length of I810. 

8.7 FLX Messages 

The following sections list FLX messages, describe the meaning of each message, and suggest 
any action necessary to correct errors. 

FLX has three types of messages: informational, warning, and error. 

Errors encountered by FLX during processing are reported on the initiating terminal. 

Error messages describe a condition that caused FLX to terminate the processing of a command. 
When this occurs, FLX returns to the highest level of command input. For example, if the 
command is entered in response to the Monitor Console Routine (MCR) prompt, FLX will issue 
the error message, exit, and prompt you with the MCR prompt, as follows: 

>FLX coninandline 
FLX — message 
> 

If the command is entered in response to the FLX prompt, FLX will issue an error message and 
prompt you with the FLX prompt, as follows: 

FLX>coiimandline 
FLX -- message 
FLX> 
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8.7.1 FLX Informational Message 

FLX issues the following informational message: 

FLX — Request terminated — last block not written 

Explanation: A carriage return was given to indicate that no new volume would be mounted 
when an end-of-volume was encountered on cassette output. The block that FLX was 
attempting to write when it encountered the end of the cassette has not been written. 
Therefore, the output file is incomplete. 

User Action: No user action is required. 

8.7.2 FLX Warning Messages 

FLX issues the following warning messages: 

FLX — WARNING — Input file out of sequence 

Explanation: A multivolume cassette file is being accessed out of sequence. 

User Action: The transfer will continue unless you terminate it by means of the ABORT 
command. 

FLX— WARNING — Specified record size bad, 512. used 

Explanation: The record size n specified with the /FA, /FB, or /IM switch is not acceptable. 
A record size of 512io bytes is assumed. 

User Action: No user action is required. 

8.7.3 FLX Error Messages 

FLX issues the following error messages: 

FLX — Bad list file spec 

Explanation: One of the following was specified: 

• More than one output file for a directory listing operation (using either the /LI or /DI 
switch) 

• Wildcards in the output file specification for a directory operation (using either the /LI 
or /DI switch) 

User Action: Enter the correct command line. 
FLX — Bad response 

Explanation: Z was entered in response to the following message: 

Mount new cassette (Y, Z (output only) or CR) 
FLX> 

The cassette in question is an input volume. 

User Action: Enter Y or CR after the message is redisplayed. 
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FLX— Can't open @ die 

Explanation: The specified indirect command file could not be opened for one of the following 
reasons: 

The file is protected against access. 

A problem exists on the physical device (for example, the disk is not spinning). 

The volume is not mounted or is allocated to another user. 

The volume is not on line. 

The specified file directory does not exist. 

The named file does not exist in the specified directory. 

User Action: Correct the condition and reenter the command line. 

FLX — Cassette error I/O terminated 

Explanation: A hardware error occurred during the end-of-volume sequence on a cassette 
volume. The transfer was aborted. 

User Action: Use a new cassette and reenter the command line. 

FLX — CO Hies to output device not allowed 

Explanation: An illegal output device (for example, magnetic tape) was specified with /CO. 
User Action: Reenter the command line without the /CO switch specified. 

FLX — Command syntax error 

Explanation: The command was entered in a format that does not conform to syntax rules. 
User Action: Reenter the command line with the correct syntax. 

FLX — Conflicting transfer modes specified 

Explanation: Conflicting transfer mode switches were entered. For example: 

SYO : =DTO : FOO . OB J/IM/FB 

User Action: Reenter the command line with only one transfer mode switch specified. 

FLX — Device handler missing 

Explanation: The device driver for a device specified in the command line is not loaded in 

the system. 

User Action: Load the appropriate device driver in the system and reenter the command 

line. 

FLX — Device size exceeds 65K blocks 

Explanation: The DU device selected as an RT-11 device is not an RC25, RCF25, RD51, 
RD52, RD53, or RX50. Devices greater than 65K blocks cannot be supported with FLX. 

User Action: Specify a valid RT-11 device and reenter the command line. 
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FLX— DOS-1 1 or RT-1 1 Device not valid format 

Explanation: The device specified with the /DO switch has an incorrect DOS-1 1 file struchire, 
or the device specified with the /RT switch has an incorrect RT-11 file struchire. 

User Action: Identify the file structure on each volume correctly, and then reenter the 
command line. 

FLX— DT: UFD fuii 

Explanation: The DECtape directory is full. 

User Action: Delete all unnecessary files, and then reenter the command line. 

FLX — End of voiume on cassette 

iVlount new cassette? (Y, Z (output oniy) or CR) 

Explanation: The physical end-of-tape was encountered during a cassette transfer. The tape 
is rewound and you are asked to mount the next cassette. 

User Action: See Section 8.4.2 if an output transfer is being performed or Section 8.4.3 if an 
input transfer is being performed. 

FLX — Error during directory I/O 

Explanation: One of the following conditions may exist: 

1. The volume is not write-enabled. 

2. The /DO, /RT, or /RS switch is specified incorrectly. 

3. The volume is not in the proper format. 

4. A hardware error occurred during a directory I/O operation (for example, bad tape). 

User Action: The following responses correspond (by number) to the conditions listed in the 
explanation: 

1. Write-enable the volume. 

2. Respecify the /DO, /RT, or /RS switch correctly. 

3. No recovery is possible with the volume currently mounted. Mount a volume that is in 
the proper format and retry the operation. 

4. Reenter the command line. 
FLX — File already exists 

Explanation: The specified output file already exists on the output device. 
User Action: Use a new or corrected file name and reenter the file specification. 
FLX— File not found 

Explanation: The named file does not appear, as specified, in the requested directory. 
User Action: Specify the file name and directory correctly, and reenter the command line. 
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FLX — @ file nesting exceeded 

Explanation: More than one level of indirect command file was specified. 

User Action: Reenter the command line with only one level of indirect command file 

specified. 

FLX — @> file syntax error 

Explanation: A syntax error occurred in the indirect command file. 

User Action: Edit the indirect command file. Run FLX again by using the corrected indirect 

command file. 

FLX — FMTD ASCII Record format bad 
or 

FLX — FMTD binary record format bad 

Explanation: Either the file is corrupted or is not of the specified type. 

User Action: If the file is corrupted, no recovery is possible. If the file type is incorrect, 
reenter the command line with the correct transfer mode switch specified. 

FLX— Illegal /BS size— Use <N <=512. and even 

Explanation: An illegal block size was specified with the /BS switch on cassette output. 
User Action: Reenter the command line with a legal block size. 

FLX— Incorrect # IN/OUT specs 

Explanation: More than one input or output specification in a command was entered where 

only one is allowed. 

User Action: Reenter the command line with the proper syntax. 

FLX— invalid device 

Explanation: A device was specified that cannot be used for the purpose specified. For 
example, a line printer was specified as an input device. 

User Action: Reenter the command line with a valid device specified. 

FLX— Invalid DOS or RT-1 1 file spec 
or 

FLX— Invalid RSX file spec 

Explanation: The file specification does not conform to proper syntax or the specified 
operation could not be performed on the specified device. 

User Action: Reenter the command line with the proper syntax. 
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FLX— Invalid switch 

Explanation: A switch was entered that is not a valid FLX switch or does not conform to 
proper syntax. 

User Action: Reenter the command line with a correct switch specification. 

FLX— I/O error 

Explanation: One of the following conditions may exist: 

• The specified device is off line. 

• A hardware error occurred (for example, bad tape). 

User Action: Ensure that the device is on line and reenter the command line. If a hardware 
error recurs, recovery may not be possible. 

FLX— I/O Error deleting linked file 

Explanation: An uncorrectable error occvirred while a DOS linked file was being deleted. 

User Action: No user action is required. The file is effectively deleted, but the volume may 
be corrupted. 

FLX — I/O error initializing directory 

Explanation: One of the following conditions may exist: 

• The specified device is not on line. 

• The specified volume is not moimted. 

• A hardware error occurred (for example, bad tape). 

User Action: Ensure that the device is on line and operable. Reenter the command line with 
the required switch specified. 

FLX — I/O error on commend input 

Explanation: An unexpected error in conmiand input was encountered from either an indirect 
command file or from the initiating terminal; FLX exits. 

User Action: Restart FLX. 

FLX — I/O error on FLX temporary file 

Explanation: FLX encountered an error condition with its temporary file. FLX creates a 
temporary file on SYO for operations involving DOS-11 CT, DT, or MT volumes. This error 
occurs when one of the following conditions exists: 

• SYO is not on line and mounted. 

• SYO is vmte-locked. 

• A protection violation occurred. 

• A hardware error was encountered. 

User Action: Correct the error condition and reenter the command line. 
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FLX — I/O error on list file 

Explanation: An error occurred or\ the output device durir\g a directory listing operation 
(using either the /LI or /DI switch). There is a hardware problem with the output device 
(for example, a device powered down). 

User Action: Correct the condition and reenter the command line. 

FLX — Output device full 

Explanation: The DOS-11 or RT-11 output volume does not contain enough space for the 
output file. 

User Action: Delete all unnecessary files and reenter the command line. 

FLX — Output tile spec not allowed 

Explanation: An output file specification was entered for an operation that does not allow 
one. 

User Action: Reenter the command line without an output file specification. 

FLX — Record too large 

Explanation: FLX detected an input record in a Files-11 transfer that is larger than the 
specified or implied record size for the file; that is, the file is corrupted. 

User Action: The file in question is unusable. 

FLX — Unable to allocate file 

Explanation: No space is available on the DOS-11 or Files-11 volume for the specified file. 
User Action: Delete all unnecessary files and reenter the command line. 

FLX — Unable to open file 

Explanation: A specified input or output Files-11 file could not be opened. The possible 
reasons are as follows: 

• The input file does not exist. 

• The volume is not mounted. 

• A protection violation occurred. 

User Action: Correct the condition and reenter the command line. 

FLX — Unable to open list file 

Explanation: The list file cannot be opened under the specified file name and directory, or 
the specified volume may not be a valid Files-11 volume. 

User Action: Specify the correct file name and directory and reenter the command line. 

FLX — Undiagnosabie request 

Explanation: FLX does not recognize the command line syntax. 
User Action: Reenter the command line with the proper syntax. 
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FLX — /CO flie from input device not ollowed unless BL: spec 

Explanation: When transferring files from MT, PR, or CT volumes, the /CO switch can only 
be specified when the /BL switch is also specified. 

User Action: Specify the /BL switch and reenter the command line. 

FLX — in UIC not oiiowed 

Explanation: A wildcard was detected in the UIC of a file specification. 
User Action: Reenter the command line with the UIC explicitly specified. 

FLX — In version number not allowed 

Explanation: A wildcard was detected in the version number field of a file specification. 
User Action: Reenter the command line with all version numbers explicitly specified. 

FLX — Illegal density value 

Explanation: Either the specified density value is not supported by the target tape drive or 
some value other than 800 or 1600 bpi was input. 

User Action: Reenter the command with the proper density value. 
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Chapter 9 

Disk Volume Formatter (FMT) 



The Disk Volume Fonnatter (FMT) utility formats and verifies disk cartridge, disk pack, fixed 
media disk, and flexible disk volumes under any RSX-1 IM-PLUS operating system that includes 
online formatting support in the Executive. (Check with your system manager to determine 
whether your system includes this feature.) 

In general, FMT performs the following functions: 

• Writes a complete header for each sector of the volume it is formatting. 

• Verifies the address contents of each sector header. 

• Sets the density for RX02 (DY-type) diskettes. 

• Lets you specify an error limit for the volume being formatted. FMT terminates processing 
when the error limit is reached. 

• Lets the Bad Block Locator task run (spawn) if your system permits spawned tasks. 

FMT can also be invoked through the DIGITAL Command Language (DCL) command 
INITIALIZE/FORMAT. Refer to the RSX-llM-PLUS Command Language Manual for more 
information. 

9. 1 FMT Command Line 

You can invoke FMT by using any of the methods described in Chapter 1. The command line 
for FMT is shown next. 

Format 

ddnn:[/switch[...]] 

Parameters 

ddnn 

Specifies the volume you are formatting. 
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switch 

Specifies an FMT switch. A list of FMT switches is given in Table 9-1. Detailed descriptions 
and examples of the switches are given in Section 9.1.1. 

Note 

Not all switches can be used with all device types. 



Table 9-1: FMT Switches 



Switch 



Format 



Function 



Bad 



Density 



Error Limit 



Manual 
Noverify 
Override 
Verify 



/BAD 



/DENS=option 



/ERL=r 



Indirect Command /@y 
File 



/MAN 

/NOVE 
/-VE 

/OVR 
/VE 



Write Last Track /WLT=n 



Runs the Bad Block Locator task if it is installed on the 
system. 

Selects options HIGH (double) or LOW (single) density 
for DY- and DU-type diskettes. 

Determines the number of errors FMT will allow on 
the volume. 

Informs FMT that it is receiving input from an indirect 
command file that you have created. An FMT com- 
mand in this form does not allow operator intervention 
in the process. 

Enters manual operating mode and formats the sector 
or track you specify. 

Inhibits the default verification of a successful FMT 
operation. 

Overrides or ignores the Manufacturer's Detected Bad 
Sector File (MDBSF). 

Verifies that an FMT operation was successfully com- 
pleted. This switch is the default. 

Rewrites the MDBSF (on the last track of the device) 
to add bad sectors found during FMT operation. 



To terminate FMT, press CTRL/Z following the FMT prompt, as explained in Chapter 1 of this 
manual. 

9. 1 . 1 FMT Switch Descriptions 

The following sections describe the switches you can use with FMT. The descriptions include 
information on restrictions for formatting specific devices and default values for the switches, 
where appropriate. 
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9.1.1.1 Bad 

The Bad switch (/BAD) spawns the Bad Block Locator task (BAD) after FMT completes its 
processing. BAD tests for the number and location of any unusable blocks. BAD records this 
bad-block information, which is used by the initializing function. If BAD is not installed on the 
system, FMT prints a warning message on your terminal and exits. 

Note that the /BAD switch can oiUy be used with operating systems that allow spawning of 
tasks. The RSX-llM-PLUS operating system provides spawned tasks as a system generation 
option. 

9.1.1.2 Density 

The Density switch (/DENS) sets DY-type diskettes to either HIGH (double) or LOW (single) 
density, and it sets DU-type (RX33) diskettes to HIGH (double) density. The default is low 
density. (This switch can also use SINGLE and DOUBLE as options.) 

Format 

ddnn:/DENS=option 

Parameters 

ddnn 

Specifies the device to be formatted. 

option 

Specifies one of the two densities, as follows: 

• HIGH (or double) 

• LOW (or single) 

9.1.1.3 Error Limit 

The Error Limit switch (/ERL) sets the error limit for the volume you are formatting. If the error 
count reaches this limit, FMT generates an appropriate message and terminates the operation. 
The default error limit is 256io errors. 

Format 

ddnn:/ERL=n 

Parameter 

n 

Specifies the error limit. Any value for n greater than or less than or equal to 256io is 
valid. 



Disk Volume Formatter (FMT) 9-3 



9. 1 . 1 .4 Indirect Command File 

In the method of operation that uses the Indirect Command File switch (/@Y), FMT will 
not generate any operational messages or warnings to your terminal. No user intervention is 
possible until the FMT operation is complete. 

To run FMT from an indirect command file, FMT must be installed before hand. Otherwise, 
you will receive an error message and the FMT operation will not run. 

Example 

To format a DK-type volume using an indirect command file, create the indirect command file 
FMTIND.CMD (you can specify any file name) that contains the following: 

FMT DK3:/«Y 

Then issue the following command from the prompt: 

>«FMTIND [RET] 

FMT will start to format the disk, DK3, and the /@Y switch will inhibit any FMT message from 
printing on your terminal. 

9.1.1.5 IVIanual 

The Manual switch (/MAN) puts FMT in manual operating mode and permits you to format 
an individual sector (or track for DM-type disk cartridges) of a device. FMT assumes cylinder, 
track, and sector numbers are decimal values unless they are preceded by a number sign (#), 
which indicates octal values. 

Manual operating mode cannot be used with DY-type devices. 

In manual operating mode, FMT displays the following message and prompts: 

** WARNING - Data will be lost on ddnn: ** 

Continue [Y OR N]? 

Entering manual mode 

Cylinder= 

Track 

Sector = 

Operation complete 

9.1.1.6 Noverify 

The Noverify switch (/NOVE or /-VE) inhibits the operation performed by the default /VERIFY 
switch (/VE). 

9.1.1.7 Override 

The Override switch (/OVR) causes FMT to ignore the MDBSF on DL-, DM-, and DR-type 
disk volumes. When FMT writes headers on these disks, it normally sets bad sector flags in 
those headers marked bad in the MDBSF. When the verification process discovers a bad sector, 
it reports that the sector was marked in the MDBSF. The /OVR switch inhibits the reporting 
operation. 
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9.1.1.8 Verify 

The Verify switch (/VE) confirms that an FMT operation was successful. It does this by reading 
back the headers and by determining if they were written correctly. This switch is the default. 

9.1.1.9 Write Last Tracl< 

The Write Last Track (/WLT) switch, when used with the /VE switch on DM- and DR-type 
volumes, rewrites the MDBSF to add the bad sectors that FMT found to the bad sectors already 
in the MDBSF. FMT also rewrites each bad sector's header to flag it as a bad sector. 

Note 

The /VE switch is the default. The /NOVE switch should not be specified. 

The /WLT switch must be specified when using FMT on a DL-type device. 

Format 

ddnn:/WLT=n 

Porometers 

ddnn 

Specifies the volume you are formatting. 

n 

Specifies the volume's pack serial number (in decimal). 

9.2 Modes of FMT Operation 

FMT lets you format volumes in two operating modes: normal and manual. In normal operating 
mode, FMT formats the entire volume. In manual operating mode, FMT permits you to format 
individual sectors (or tracks for DM-t3Ape disks) that you specify in response to FMT prompts. 
FMT uses normal operating mode unless you specify manual mode with the /MAN switch in 
the command line. 

FMT normally retries an operation when it encounters an error. If the operation still fails, FMT 
flags the sector as bad and displays the following message: 

FMT ~ Error writing header 

If FMT encounters an error during the verification operation, it prints one of the follovring 
messages on your terminal: 

FMT -- Error reading header 

or 

FMT -- Header compare error 

FMT then continues the verification operation. 
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9.2.1 Normal Operating 

When you invoke FMT in normal operating mode (without the /MAN switch), FMT prints the 
following message: 

** WARNING - Data will be lost on ddnn: ** 
Continue? [Y or N] 

Caution 

If you answer Yes, FMT erases all data previously stored on the disk. 

After a Y (Yes) response, FMT returns the following message: 

Start formatting 

It then performs the formatting functions you specify with switches in the FMT command line. 
After an N (No) response or a carriage return, FMT returns control to the system monitor. 

Normal FMT operation varies slightly according to the volume you are formatting (see 
Section 9.3). 

9.2.2 Manual Operating 

If you specify manual operating mode (using the /MAN switch), FMT prints the follov«ng 
warning: 

** WARNING - Data will be lost on ddnn: ** 
Continue? [Y or N] 

Caution 

If you answer Yes, FMT erases all data previously stored on the disk. 

After a Y (Yes) response, FMT returns the following message: 

Entering manual mode 

It then displays the following prompts: 

Cylinder= 
Track 
Sector = 

After you enter your response to the prompts, FMT formats the sector or track you specify. 
FMT assumes the responses are in decimal unless they are preceded by a number sign ( # ) to 
indicate an explicit octal response. If you enter a parameter that is out of the range for the 
volume, FMT returns an error message and exits. Table 9-2 lists the valid ranges for FMT 
manual mode operations. 

Note that FMT manual operating mode cannot be used with RX02 diskettes. 

FMT maniial operating mode works the same on all disk volumes, with one exception: On 
DM-type volumes (RK06 and RK07), FMT formats a specific track. 
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Example 

FMT>DMO:/MAN [M] 

Causes FMT to prompt with the following message: 

** WARNING - Data will be lost on DM0: ** 
Continue? [Y or N] Y [M] 
Entering manual mode 
Cylinder" 237 [RET] 
Track = 1 \M} 

Formats the entire track you specified. 

Table 9-2: Ranges for Manual FMT Operations 



Device Sectors Tracks Cylinders 



RP02/RPR02 


0-9 


0-19 


0-199 


RP03 


0-9 


0-19 


0-399 


RP04 


0-21 


0-18 


0-410 


RP05 


0-21 


0-18 


0-410 


RP06 


0-21 


0-18 


0-814 


RK05/RK05F 


0-11 


0-1 


0-199 


RK06 


0-21 


0-2 


0-410 


RK07 


0-21 


0-2 


0-814 


RM02 


0-31 


0-4 


0-822 


RM03 


0-31 


0-4 


0-822 


RM05 


0-31 


0-18 


0-822 


RM80 


0-31 


0-13 


0-558 



9.3 FMT-Supported Disk Volumes 

The following sections describe using normal FMT operating mode with the different types of 
FMT-supported devices. Table 9-3 lists the disk volumes that allow formatting and their device 
mnemonics. 

Table 9-3: FMT-Supported Disk Volumes 
Disk Volumes Device Mnemonic 



RP04 disk pack 


DB 


RP05 disk pack 


DB 


RP06 disk pack 


DB 
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Table 9-3 (Cont.): FMT-Supported Disk Volumes 



Disk Volumes Device Mnemonic 



RK05 disk cartridge 


DK 


RK05F fixed media disk 


DK 


RLOl disk cartndge 


DL 


RL02 disk cartridge 


DL 


RK06 disk cartridge 


DM 


RK07 disk cartridge 


DM 


RPR02 disk pack 


DP 


RP02 disk pack 


DP 


RP03 disk pack 


DP 


RM02 disk pack 


DR 


RM03 disk pack 


DR 


RM05 disk pack 


DR 


RM80 fixed media disk 


DR 


RX33 diskettes 


DU 


RX02 diskettes 


DY 



The status FMT requires for the disk volumes varies with the operating system. 

On an RSX-llM-PLUS operating system, the disk volume must be mounted with foreign 
characteristics by using the MOUNT/FOREIGN command. 

9.3. 1 DB-Type Devices (RP04/RP06/RP06 Disk Paclcs) 

When FMT formats a DB-type volume, it tries to write 22 sector headers at a time until it 
has formatted the entire volume. If FMT encounters an error, it attempts to write each header 
individually and designates which headers are bad. 

Unless you specify the No Verify switch (/-VE), FMT verifies 11 headers at a time until it has 
verified the volume. If FMT encounters an error, it attempts to verify the headers individually 
to determine where the error occiirred. It then reports any bad headers and continues the 
operation. 

9.3.2 DK-Type Devices (RK05 Dlsl< Cartridge or RK05F Fixed iVIedia Dlsl<s) 

When FMT formats a DK-type volume, it tries to write each sector header individually until it 
has formatted the entire volume. If FMT encounters an error, it retries each header before it 
reports the header as bad. 

Unless you specify the /-VE switch, FMT verifies 12 headers at a time until it has verified the 
volume. If FMT encounters an error, it attempts to verify the headers individually to determine 
where the error occurred. It then reports any bad headers and continues the operation. 
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9.3.3 DL-Type Devices (RL01/RL02 Disk Cartridges) 

FMT does not format a DL-type volume, but it reads each block, one track at a time, and 
determines which blocks were marked as bad by the manufacturer's formatting process. If the 
MDBSF is corrupt or has been written over, FMT then rewrites the MDBSF on the last track 
with this information. When using FMT on a DL-type device, the Write Last Track switch 
(/WLT) must be specified. 

9.3.4 DiVI-Type Devices (RK06/RK07 Disic Cartridges) 

FMT writes DM-type headers one track (22 sectors) at a time and sets the header flags of those 
sectors marked bad in the MDBSF. If FMT encounters errors, it retries the operation before it 
designates which headers are bad. 

Unless you specify the /-VE switch, FMT verifies that each sector from to 21 is addressable. 
It does this by issuing a full 256-word write, made up of the 2-word address pattern (the sector 
number and its complement) into each sector. Once the track has been written, each sector is 
read and the full 256 words of data are compared with the expected data pattern. If an error 
occurs during this operation, FMT reports that sector as bad and continues the operation. 

When FMT writes headers on DM-type devices, it sets bad sector flags in the headers already 
marked as bad in the MDBSF. Unless you specify the /-VE switch, FMT indicates whether the 
bad sector was flagged in the MDBSF. 

9.3.5 DP-Type Devices (RPR02/RP02/RP03 Disl< Pacics) 

When FMT formats a DP-type volume, it tries to write 10 headers at a time until it has 
formatted the volume. If FMT encounters an error, it attempts to write each header individually 
and designates which headers are bad. 

Unless you specify the /-VE switch, FMT verifies 10 headers at a time until it has verified the 
volume. If FMT encounters an error, it attempts to verify the headers individually to determine 
where the error occurred. FMT reports that sector as bad and continues the operation. 

9.3.6 DR-Type Devices (RIVI02/RIVI03/RiVI05/RiVI80 Disi< Paci<s) 

When FMT formats a DR-type volume, it tries to write 32 headers at a time until it has 
formatted the volume. If FMT encounters an error, it attempts to write each header individually 
and designates which headers are bad. 

Unless you specify the /-VE switch, FMT verifies 16 headers at a time until it has verified the 
volume. If FMT encounters an error, it attempts to verify the headers individually to determine 
where the error occurred. It then reports any bad sectors and continues the verification operation. 

When FMT writes headers on DR-type volumes, it sets bad sector flags in headers already 
designated as bad by the MDBSF. Unless you specify the /-VE switch, FMT indicates whether 
the sector was marked bad in the MDBSF. 

On the RM80 disk, in addition to performing the functions indicated for other DR devices, FMT 
reads a skipped sector file to identify the sectors that the manufacturer's formatter designated as 
"skipped sectors," and then it sets the skipped sector flag bit in the appropriate sector headers. 
All data originally intended for a sector designated as a skipped sector is moved to the following 
sector (for more information, see the RSX-llM-PLUS I/O Drivers Reference Manual). 
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9.3.7 DU-Type Devices (RX33 Diskettes) 

To format an RX33 diskette as an RX33, the unit must be mounted foreign. The DENSITY 
switch (/DENS) is the only switch that is applicable for formatting an RX33 and HIGH is the 
only density for RX33 diskettes. 

Format 

DUnn:[/DENS=HIGH] 

The actual formatting of the RX33 will be done by the controller unlike the formatting of other 
devices, which is done by FMT. 

9.3.8 DY-type Devices (RX02 Disl<ettes) 

You can use FMT to set an RX02 diskette to either HIGH (double) or LOW (single) density by 
using the Density switch (/DENS). Unless you specify the /-VE switch, FMT writes and reads 
block and the last block on the diskette to determine that the density is consistent. 

Format 

FMT DYnn:[/DENS=option] 

Parameter 

option 

Specifies one of the two densities, as follows: 

• HIGH (or double) 

• LOW (or single) 

Manual operating mode cannot be used with DY-type devices. 

9.4 FMT Error Messages 

Error messages describe a condition that caused FMT to terminate the processing of a command. 
When this occurs, FMT returns to the highest level of command input. For example, if the 
command is entered in response to the Monitor Console Routine (MCR) prompt, FMT will issue 
the error message, exit, and prompt you with the MCR prompt, as follows: 

>FMT commandline 
FMT — message 
> 

If the command is entered in response to the FMT prompt, FMT will issue an error message 
and prompt you with the FMT prompt, as follows: 

FMT> c ommauidline 
FMT — message 
FMT> 

This section describes the error messages FMT issues and lists possible user responses. 
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FMT — Command I/O error 

Explanation: A hardware transmission error occurred from the keyboard. 
User Action: Reenter the command. 

FMT — Command too long 

Explanation: The command was longer than 8O10 characters. 
User Action: Enter a shorter command. 

FMT — Device does not support formatting 

Explanation: A device was specified that does not allow the use of FMT. 

User Action: Determine the correct device and, if FMT operation is legal, reenter the 
command. 

FMT — Device driver missing 

Explanation: The disk device driver is not loaded. 

User Action: Load the driver (if it is loadable) and reenter the command, or use a different 
device in the command line. 

FMT — Device not in system 

Explanation: The specified device was not identified as part of the system during system 
generation or the device does not exist on the system hardware configuration. 

User Action: Detemune the correct command line with the correct device mnemonic and 
reenter the command line. 

FMT — Device not ready 

Explanation: The disk volume was not at operating speed when FMT attempted to access it. 

User Action: Allow the volume to reach operating speed, and then reenter the FMT 
command. 

FMT — Device offline 

Explanation: The device is not in the system hardware configuration. 

User Action: Ensure that the device name is correct, put the device on line, and then reenter 
the command line. 

FMT — Device write locited 

Explanation: The volume is write-locked; any write access is prohibited. 
User Action: Write-enable the unit and reenter the FMT command. 
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FMT — Disk is an alignment cartridge 

Explanation: The device is a factory-created disk used to align the heads in a disk drive and 
should not be used for other purposes. 

User Action: Use a disk that is not an alignment cartridge and reenter the FMT command. 

FMT — Error limit exceeded 

Explanation: The number of errors FMT found on the disk exceeded either the number of 
errors specified with the /ERL switch or the default 256io error limit that FMT sets. 

User Action: Set a higher error limit if the /ERL switch was used. 

FMT — Error reading data 

Explanation: FMT encountered an error when it tried to read data from a disk. 

User Action: No user action is required. FMT retries the operation and continues the 
verification. 

FMT — Error setting disicette density 

Explanation: FMT tried to format an RX02 diskette but the operation failed. 
User Action: Check the syntax and reenter the command with the density reset. 

FMT — Error writing data 

Explanation: FMT encountered an error when it tried to write sector headers. 

User Action: No user action is required. FMT retries the operation and continues the 
verification. 

FMT — Error writing header 

Explanation: FMT encountered an error when it tried to write a header. 
User Action: No user action is required. FMT retries the operation. 

FMT — Failed to attach device 

Explanation: FMT could not attach the device to be formatted. 

User Action: Determine whether another task has attached the device. If so, wait until the 
task exits, or abort the task and run FMT again. 

FMT — Failed to format - Volume has been altered 

Explanation: An error occurred while the disk was being formatted. The FMT operation did 
not complete, but the volume may have been altered. 

User Action: Reenter the FMT command line. 
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FMT — Failed to read Manufacturer's Bad Sector File 

Explanation: A disk hardware error occurred while FMT tried to read the MDBSF on the 
last track of a device. 

User Action: Include the /OVR switch and reenter the command. 

FMT — Fatal hardware error 

Explanation: A fatal error occurred in the system hardware configuration. 
User Action: Contact your DIGITAL Field Service representative. 

FMT — Header compare error 

Explanation: FMT found an error when it tried to compare headers with the expected value 
during a verification error. 

User Action: No user action is required. FMT tries the operation again. 

FMT— Invalid switcti 

Explanation: An illegal switch or a switch not valid for the specified device was used in an 
FMT command. 

User Action: Check the syntax and reenter the command. 

FMT— Invalid value for ttie /DENS switcti 

Explanation: The value for the /DENS switch was invalid for the device specified. 

User Action: Refer to Section 9.1.1.2 for information on options for the /DENS switch. 
Specify the correct density and reenter the command line. 

FMT — Manufacturer's Bad Sector File corrupt 

Explanation: The factory-written bad block data file (MDBSF) on the last track of the disk is 
in an unusable format. 

User i^cfion: Reenter the command with the /OVR switch to prevent FMT from trying to 
use the corrupt bad block data. 

FMT — Marked bad in Manufacturer's Bad Sector File 

Explanation: Indicates that bad block information is recorded in the MDBSF on the disk. 
User Action: No user action is required. This message is for your information only. 

FMT — Marked defect In Skip Sector File 

Explanation: The sector flagged previous to this message was marked as bad in the Skip 
Sector File. 

User Action: No user action is required. 
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FMT — Media format error - Volume has been altered 

Explanation: A transmission error occurred while the volume was being formatted. The FMT 
operation has not completed, but the volume may have been altered. 

User Action: Reenter the FMT command line. 

FMT — Parity error on device 

Explanation: A parity error occurred during the FMT operation. 

User Action: Reenter the command line. If the error persists, the volume may need to be 
replaced. 

FMT — Privilege violation 

Explanation: FMT attempted an operation on a device that was mounted or allocated to 
another user, was mounted Files-1 1, or was not mounted foreign. 

User Action: Ensure that the device is mounted foreign by the user and reenter the command 
line. 

FMT — Response out of range 

Explanation: Parameters entered for manual formatting of an individual sector or track were 
out of the range for the volume. 

User Action: Check Table 9-2, (Section 9.2.2) for valid parameters and reenter the command. 
FMT — Skip Sector File Is corrupt, reading next 

Explanation: The current copy of the Skip Sector File is corrupt. FMT ignores the copy and 
proceeds to the next copy. 

User Action: No user action is required. 

FMT — Syntax error 

Explanation: FMT detected a syntax error in the command line. 
User Action: Determine the correct command syntax and reenter the command. 
FMT — Unable to read any Skip Sector File 

Explanation: FMT was unable to read any copy of the Skip Sector File found on the first 
track of the CE cylinder area on the RM80 disk. 

User Action: No user action is required. 

FMT — Unable to run badblock utility 

Explanation: An FMT command specified the /BAD switch, but the Bad Block Locator task 
(BAD) could not be spawned. Either the operating system does not spawn tasks or BAD is 
not installed. 

User Action: Run BAD separately (see Chapter 2 for more information). 
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FMT — Unrecoverable error - n 

Explanation: An I/O error (n) caused FMT to terminate. 

User Action: Reenter the FMT command and, if the error occurs again, try the command 
with a different device specified, or refer to the error codes in the RSX-UM-PLUS and 
Micro/RSX 1/0 Operations Reference Manual. 

FMT — Vector not multiple of four 

Explanation: The message occurs only when using standalone BRU (BRUSYS). 

The vector specified was not a multiple of four. 

User Action: Specify the correct vector and reenter the command line. 

FMT— Verify operation of FMT failed 

Explanation: FMT detected that the controller initiated format was not sucessful and that 
some of the blocks on the volume were not readable. 

User Action: Reenter the command line. If the error persists, the volume may need to be 
replaced. 

FMT — WLT switch Is missing 

Explanation: The /WLT switch was not specified in the command line for formatting a 
DL-t5rpe device. 

User Action: Specify the /WLT switch and reenter the command line. 
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Chapter 10 



Librarian Utility Program (LBR) 



The Librarian Utility Program (LBR) allows you to create, update, modify, list, and maintain 
library files. A library file is a direct access file that contains a collection of related files. LBR 
organizes files, usually with the same file type, into library modules so that you have rapid and 
convenient access to your files. 

10.1 Library Files 

Library files contain two directory tables: the entry point table (EPT) and the module name 
table (MNT). The EPT contains entry point names that consist of global symbols defined as 
entry points in MACRO source programs. The MNT contains names of the modules in the 
library. Both tables are ordered alphabetically. 

The following sections describe the three tj^jes of libraries: object, macro, and universal. 

10.1.1 Object Library Files (OLB) 

Object library files contain object files (OBJ type). The module names are derived from .TITLE 
directives, while the entry point names are derived from global symbols defined in the module. 
LBR references the module code in the library by the module name. The source program 
references object library modules by the entry point name. Entry points apply only to object 
libraries. 

You use object module libraries as input to the Task Builder (TKB). TKB searches for definitions 
of all global symbols referenced in a program in the following manner. First, TKB searches the 
other modules specified, then it searches the specified user- written object module library, and, 
finally, it searches the system library. 
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10.1.2 Macro Library Files (IVILB) 

Macro library files contain source macro files (MAC type). The module names are derived from 
.MACRO directives. From each macro definition, LBR extracts the name and creates an entry 
in the MNT. The entry in the MNT is the means by which the assembler finds the associated 
macro definition in the library. 

You use macro library modules as input to the MACRO-11 assembler. The assembler searches 
the specified library for macros listed in .MCALL statements and called in the source program 
before searching the System Macro Library. 

10.1.3 Universal Library Files (ULB) 

Universal library files contain modules inserted from any kind of file, whether it be a program 
or text. The module names are either user specified with the Insert switch (/IN) or derived 
from the file name at the time of insertion. 

Primarily, you use universal libraries to package related files together. You can reference a 
universal library module in a program by using the Universal Library Access ($ULA) system 
library routine. This routine, specified in the macro source program, establishes the necessary 
conditions for access (read only) to a universal library module. (For more information on $ULA, 
see the RSX-llM-PLUS and Micro/RSX System Library Routines Reference Manual.) 

You can invoke LBR by using any of the methods for invoking a utility, as described in 
Chapter 1. 

10.1.4 Format of Library Files 

A library file consists of a library header, an EFT, an MNT, the library modules and their 
headers, and any available space. The EFT has zero length for macro and universal libraries. 
Figure 10-1 illustrates object and macro library file formats, and Figure 10-2 illustrates universal 
library file format. 

10.1.4.1 Library Header 

The header section is a full block in which the first 24io words are used to describe the 
current status of the library. The header's contents are updated as the library is modified. This 
allows LBR to access the necessary information to perform its functions (for example, to insert, 
compress, and delete files). The twenty-fourth word in the library header is the default insert 
file type for universal libraries and is undefined for macro and object libraries. See Figure 10-3. 

10.1.4.2 Entry Point Table 

The entry point table (EPT) consists of 4-word elements that contain an entry point name (words 
to 1) and a pointer to the module header of the module where the entry point is defined 
(words 2 to 3). (See Figure 10-4.) This table is searched when a library module is referenced 
by one of its entry points. The table is sequenced in order of ascending entry point names. 
The EPT applies only to object library files. The Byte in Block in Figure 10-4 is the record size 
word followed by the module header (see Figures 10-6 and 10-7). 
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10.1.4.3 Module Name Table 

The module name table (MNT) is searched when the library module is referenced by its module 
name rather than by one of its entry points. It is made up of two 4-word elements: a module 
name (words to 1) and a pointer to the module header (words 2 to 3). (See Figure 10-5.) The 
MNT presents the module names in ascending order. The Byte in Block in Figure 10-5 is the 
record size word followed by the module header (see Figures 10-6 and 10-7). 

10.1.4.4 Module Header 

Each module starts with a header of eight words for object and macro modules and 32io words 
for universal modules. The module header contains information about the module such as the 
type and status of the module, its length (number of words), and its attributes. See Figures 10-6 
and 10-7. 

The File Descriptor Block (FDB) of the original file from which the module was created has five 
sections of information; the first is "file attributes." These attributes are as follows: 

• Record tjrpe 

• Record attribute 

• Record size 

• Highest virtual block 

• End-of-file (EOF) block number 

• Optional information 

When you create a file and insert it into a universal library, LBR copies the input file attributes 
to the module header. You can modify some of these attributes by using the Modify Header 
switch (/MH). 

In object and universal modules, the low-order bit of the attributes byte is set if the module has 
the selective search attribute. In imiversal modides, bit 1 of the attributes bj^e is set if the input 
file was contiguous. Also, in object modules, the two words of type-dependent information 
contain the module identification defined by the .IDENT directive at assembly time. In macro 
modules, these two words are undefined. 

For universal modules, type-dependent identification is derived fi-om the file type and version 
number of the input file. 

Universal libraries allow you to change the module header, which contains optional descriptive 
information, by means of the /MH switch. 
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Figure 10-1: General Format for Object and Macro Library Files 



Fixed- 
Length 
Records 


Library 
Header 






' 


Entry Point 
Table 






Module Name 
Table 




Variable- 


Module 1 Header 




Rec 


ords 


Module 1 






• 
• 






Module N Header 






Module N 






Available Space 





Block 
Boundaries 



ZK-184-81 



10-4 Librarian Utility Program (LBR) 



Figure 10-2: Universal Library File Format 



Fixed- 
Length 
Records 


Library 
Header 








Entry Point 
Table 




' 


Module Name 
Table 




Variable- 
Length 
Records 


Module 1 Header 
Unused Space 








Module 1 












Unused Space 






Module 2 Header 
Unused Space 






Module 2 


















Unused Space 






Module N Header 
Unused Space 






Module N 












Available Space 





Block 
Boundaries 



NOTE 

All universal module headers and the first record of each 
universal module will start on a block boundary. 



ZK- 185-81 



Librarian Utility Program (LBR) 10-5 



Figure 10-3: Contents of Library Header 
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Figure 1 0-4: Format of Entry Point TobI© (EPT) Element 
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Figure 10-6: Module Header Format for Object and Macro Libraries 
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Figure 10-7: Module Header Format for Universal Libraries 
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10.2 LBR Restrictions 

The following restrictions apply when using LBR: 

• Limit of 65,536 (64ioK) words per module. 

• Limit of 65,536 (64ioK) blocks per library. 

« Tables should be allocated their anticipated maximum size. Expanding table allocations 
requires using the Compress switch (/CO) to copy the entire file. 

• A fatal error results if an attempt is made to insert a module into a library that contains a 
module with a different name, but with the same entry point, as the inserted module. For 
further information, refer to the discussion of the Insert switch (/IN) in Section 10.3.2.8. 

• The use of wildcards in file specifiers is not allowed (that is, forms such as *.OBJ, where 
the asterisk ( • ) indicates all modules with type OBJ). 

The library's tables must contain enough space for both the modules being replaced and their 
replacements because the new modules are entered and the old modules are only logically (not 
physically) deleted. 

10.3 LBR Command Line 

You can invoke LBR by using any of the methods described in Chapter 1. 

Note 

LBR allows only one level of indirect command file nesting. 

The general command line for LBR is shown next. 

Format 

outfile[,listfile]=infile[,...] 
The format for entering file specifications is as follows: 
ddnn : [directory] filename . type ; version [/switch] 

Refer to Chapter 1 for detailed descriptions of the parameters for file specifications. 
The LBR switches are summarized in Table 10-1. 

Table 10-1: LBR Switches 



Switch Format Function 



Compress 


/CO 


Create 


/CR 


Delete 


/DE 


Default 


/DP 


Delete Global 


/DG 



Compresses a library file. 

Creates a library file. 

Deletes a library module and all of its entry points. 

Specifies the default library file type. 

Deletes a library module entry point. 
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Table 10-1 (Cont.): LBR Switches 



Switch 



Format Function 



Includes entry point elements in the library EPT. 

Excludes entry point elements in the library EPT. 

Extracts (reads) one or more modules from a library file and writes 
them into a specified output file. 

Inserts a module. 

Lists module names. 

Lists module names and module entry points. 

Lists module names and full module description. 

Modifies a universal module header. 

Replaces a module. 

Does not replace a module. 

Spools the listing for printing. 

Does not spool the listing. 

Sets the selective search attribute in the module header. 

Reduces the size of the macro source. 

Does not reduce the size of a specific macro source. 



Entry Point 


/EP 




/-EP 


Extract 


/EX 


Insert 


/IN 


List 


/LI 




/LE 




/FU 


Modify Header 


/MH 


Replace 


/RP 




/-RP 


Spool 


/SP 




/-SP 


Selective Search 


/SS 


Squeeze 


/SZ 




/-SZ 



10.3.1 Defaults for LBR File Specifications 

Table 10-2 describes the defaults for LBR file specifiers. 
Table 1 0-2: LBR File Specifiers Defaults 



Specifier File 



Default 



ddnn Output file SYO 

Listing file The device that was specified for the output file; otherwise, the 
default for the output file. 

Input file For the first input file specifier, SYO. 

For subsequent input file specifiers, the device specified in the 
previous input file specifier; otherwise, the default for the previous 
input file specifier. 

directory Output file The directory under which LBR is running currently. 

Listing file The directory that was specified for the output file; otherwise, the 
default for the output file specifier. 
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Table 10-2 (Cont.): LBR File Specifiers Defaults 



Specifier 



File 



Default 



Input file 



filename 




type 


Output file 




Listing file 




Input file 


version 
switch 


Output file 




List file 




Input file 



For the first input file specifier, the directory under which LBR is 
running cxirrently. 

For subsequent input file specifiers, the directory specified in 
the previous input file specifier; otherwise, the default for the 
previous input file specifier. 

No default. Must be specified. 

Depends on the default in effect (see Section 10.3.2.4), except 
when the /CO or /CR switch is specified (see Sections 10.3.2.1 
and 10.3.2.2). 

LST 

Refer to the descriptions of the /CO (Section 10.3.2.1), /IN 
(Sections 10.3.2.8 and 10.3.2.9), and /RP (Sections 10.3.2.12 and 
10.3.2.13) switches. 

Latest version of the file, or latest version plus 1 for the output 
file when the /CO, /CR, or /EX switch is specified. 

/IN (insert) 

/SP/LI (spool and list module names) 

None. 



10.3.2 LBR Switch Descriptions 

LBR uses switches appended to file specifications to invoke functions. These switches are 
summarized in Table 10-1. 

10.3.2.1 Compress 

Use the Compress switch (/CO) to physically delete all logically deleted records, to put all 
free space at the end of the file, and to make the free space available for new library module 
inserts. Additionally, the library table specification may be altered for the resulting library. LBR 
accomplishes this by creating a new file that is a compressed copy of the old library file. The 
old library fUe is not deleted after the new file is created. 

The /CO switch can be appended only to the output file specification. 

Format 

outfile/CO:size:ept:mnt=infile 
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Parameters 

outflle 

Specifies the file specification that is to become the compressed version of the input file. 
The default file type is OLB if the input file is an object library, MLB if the input file is a 
macro library, or ULB if the input file is a universal library. 

size 

Specifies the size of the new library file in 256io-word blocks. The size of the old library 
file is the default size. 

ept 

Specifies the number of entry point table (EPT) entries to allocate. If the value specified is 
not a multiple of 64io, the next highest multiple of 64io is used. The number of EPTs in 
the old library file is the default value. This parameter is always forced to zero for macro 
libraries and universal libraries. The maximum number of entries is 4096io. 

mnt 

Specifies the number of module name table (MNT) entries to allocate. If the value specified 
is not a multiple of 64io, the next highest multiple of 64io is used. The number of MNTs 
in the old library file is the default value. The maximum number of entries is 4096io. 

inflle 

Specifies the library file specification to be compressed. The default file type is OLB for 
object libraries, MLB for macro libraries, and ULB for universal libraries. The actual default 
file tjrpe is determined by the current default library file type (see Section 10.3.2.4). 

Example 

LBR>RICKLIB/C0:100. :128. :64.=SHEILA.0LB [RET] 

Compresses file SHEILA.OLB and creates a new file, RICKLIB.OLB, with the following attributes: 

size = lOOio blocks 
ept = 128io entry points 
mnt = 64io module names 

The new file, RICKLIB.OLB, receives a version number that is one version greater than the 
latest version for the file. 

Both files, RICKLIB.OLB and SHEILA.OLB, reside in the default directory file on SYO. 

10.3.2.2 Create 

Use the Create switch (/CR) to allocate a contiguous library file on a direct access device (for 
example, a disk). The swritch initializes the library file header, the EPT, and the MNT. 

The /CR switch can be appended to the output file specification only. 

Format 

outfile/CR:size:ept:mnt:libtype:infilet)^e 
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Parameters 

outflle 

Spedfies the library file specification being created. The default file type is OLB if an object 
library is being created, MLB if a macro library is being created, or ULB if a universal library 
is being created. 

size 

Spedfies the size of the new library file in disk (256io-word) blocks. The default size is 
lOOio blocks. 

ept 

Specifies the number of entry point table (EPT) entries to allocate. The default value is 
512io for object libraries. This parameter is always forced to zero for macro libraries and 
universal libraries. The maximum number of entries is 4096io. 

mnt 

Specifies the number of module name table (MNT) entries to allocate. The default value is 
256io- The maximum number of entries is 4096io. 

libtype 

Spedfies the type of library to be created. Acceptable values are OBJ for object libraries, 
MAC for macro libraries, and UNI for universal libraries. The default is the last value 
specified or implied with the Default switch (/DF) (see Section 10.3.2.4), or it is OBJ if the 
/DF switch has not been spedfied. 

inflletype 

Specifies the default input file type for the created universal library. If this value is not 
specified, the default input file type for universal libraries is UNI. This value is not defined 
for object or macro libraries. 

Note 

If the values specified for ept and mnt are not multiples of 64io, ept and mnt are automatically 
filled out to the next disk block boundary. 

Example 

LBR>RICKLIB/CR : : 128 . : 64 . : OB J=SHEILA . LAURA . JENNY [RETI 

Performs a combination of functions. First, the library file RICKLIB.OLB is created in the default 
directory on SYO. RICKLIB has the following attributes: 

size = lOOio blocks (default size) 
ept = 128io entry points 
mnt = 64io module names 
type = OBJ 

Second, object modules from the input files SHEILA.OBJ, LAURA.OBJ, and JENNY.OBJ, which 
reside in the default directory on SYO, are inserted into the newly created library file. The Insert 
switch (/IN) is the default switch for input files (see Section 10.3.2.8). 
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10.3.2.3 Delete 

Use the Delete switch (/DE) to logically delete library modules and their associated entry points 
(global symbols) from a library file. Up to 15io library modules and their associated entry points 
can be deleted with one delete command. 

When LBR begins processing the /DE switch, it prints the following message on the initiating 
terminal: 

Modules deleted :n 

As modules are deleted logically from the library file, the module name is printed on the 
initiating terminal. (See the example at the end of this section.) 

If a specified library module is not contained in the library file, a message is printed on the 
initiating terminal and the processing of the current command is terminated. The following 
message appears: 

LBR — *FATAL* - No module named "name" 

The /DE switch can be appended only to the library file specification. 

When LBR deletes a module from a library file, the module is not physically removed from the 
file, but it is marked for deletion. This means that, although the module is no longer accessible, 
the file space that the module once occupied is not available for use (unless the deleted module 
is the last module that was inserted). To physically remove the module from the file and make 
the freed space available for use, you must compress the library (see Section 10.3.2.1). 

Format 

outfile/DE:module[. . .] 

Parameters 

outflle 

Specifies the library file specification. 

module 

Specifies the name or names of the module or modules to be deleted. 

Example 

LBR>RICKLIB/DE: SHEILA: LAURA: JENNY [RET] 

MODULES DELETED: 

SHEILA 

LAURA 

JENNY 

Deletes the modules SHEILA, LAURA, and JENNY and their associated entry points from the 
latest version of library file SY0:RICKLIB.OLB. 
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10.3.2.4 Default 

Use the Default switch (/DF) to specify the default library file type. Acceptable default values 
are OBJ for object libraries, MAC for macro libraries, and UNI for universal libraries. When a 
default library file type is not specified by the /DF switch, OBJ is the default library file type. 

Specifying a default value results in the following: 

• Sets the default file t)^e for the /CR switch. 

• Provides a file type default value of MLB for macro libraries, ULB for universal libraries, 
and OLB for object libraries when opening an output (library) file. Exceptions to this occur 
when you use the /CO or /CR switch. When you specify the /CO switch, the default 
applies to the library input file. When you specify the /CR switch, the default file type is 
OLB if an object library is being created, ULB if a universal library is being created, or MLB 
if a macro library is being created. 

The /DF switch only affects the file type of the file to be opened. After that, the library 
header record information is used to determine the type of library file being processed. 

The /DF svdtch can be issued alone or appended to a library file specification. 

Format 

outfile/DF:filetype 

or 

/DF:filetype 

Parameters 

outflle 

Specifies the library file specification. 

flietype 

Specifies the default library file type: OBJ for object library files, MAC for macro library 
files, and UNI for universal library files. 

If a value other than OBJ, ULB, or MAC is specified, the current default library type vsdll be 
set to object libraries and the following message will be displayed: 

LBR -- *FATAL* - Invalid library type specified 

Examples 

LBR>/DF:MAC [RET] 
LBR>RICKLIB= \M] 



Opens file RICKLIB.MLB for insertion. 

LBR>/DF:MAC [RETI 
LBR>RICKLIB/DF:OBJ=infile [M] 

Replaces MAC with OBJ as the default file type and opens file RICKLIB.OLB for insertion. 
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LBR>/DF:MAC [M] 
LBR>RICKLIB/CR [M 



Creates the macro library RICKLIB.MLB. 

LBR>/DF:MAC fRETl 
LBR>RICKLIB/CR::::OBJ (RET] 

Shows OBJ overriding the default (MAC) because RICKLIB.MLB is a macro library, and creates 
the object library RICKLIB.OLB. 

LBR>/DF:OBJ [RET] 
LBR>TEMP/CO=RICKLIB.MLB [Ml 

Shows MAC overriding the default (OBJ) because RICKLIB.MLB is a macro library, and creates 
the macro library file TEMP.MLB to receive the compressed output. 

LBR>/DF:UNI [RFTI 
LBR>RICHLIB=TEST [M] 

Opens file RICHLIB.ULB for insertion. 

10.3.2.5 Delete Global 

Use the Delete Global switch (/DG) to delete a specified entry point (global symbol) from the 
EPT. Up to 15io entry points may be deleted with one command. This command does not 
affect the object module that contains the actual symbol definition. You may wish to delete an 
entry point if a module to be inserted has the same entry point. 

When LBR begins processing the /DG switch, it prints the following message on the initiating 
terminal: 

Entry points deleted: 

As entry points are deleted from the library file, the entry point is printed on the initiating 
terminal. (See the example at the end of this section.) 

If a specified entry point is not contained in the EPT, a message is printed on the initiating 
terminal and the processing of the current command is terminated. This message follows: 

LBR — *FATAL* - No entry point named "nsuue" 

The /DG switch can only be appended to the library file specification. 

Format 

outfile/DG:global[...] 

Parameters 

outfile 

Specifies the libreuy file specification. 

global 

Specifies the name or names of entry point or points to be deleted. 
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Example 

LBR>RICKL IB/DG : SHEILA : LAURA : JENNY [RETI 

ENTRY POINTS DELETED: 

SHEILA 

LAURA 

JENNY 

Deletes the entry points SHEILA, LAURA, and JENNY from the latest version of the library file 
named SYO:RICKL1B.OLB. 

10.3.2.6 Entry Point 

Use the Entry Point switch (/EP) to control (include or exclude) the placement of global sjmibols 
in a library entry point table (EPT). 

Format 

outfile/EP=infile[,...] 

or 

outfile=infile/EP[,...] 

Parameters 

outflle 

Specifies the output file specification. When the /EP switch is applied to this file specification, 
LBR assumes each of the input files contains modules for which entry points are to be either 
included or excluded. 

innie 

Specifies an input file specification. When the /EP switch is applied to an input file 
specification, LBR assumes only the input files to which the switch is applied contain 
modules for which entry points are to be either included or excluded. 

The /EP switch can be specified in either a positive or negative format as follows: 

/EP Includes entry points in the EPT. 

/-EP Does not include entry points in the EPT. 
/NOEP 

The positive switch format (/EP) causes all entry points in a module or modules to be entered 
in the library EPT. 

Either negative switch format (/-EP or /NOEP) provides for a module to be included in a 
library, but excludes the entry points in that module from being entered in the library EPT. 

The /EP switch is the LBR default. If the switch is not specified, all entry points are entered 
into the library EPT. 
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The /EP switch has no effect on macro or universal libraries. 

Note 

Although not reflected in the command formats, the positive and negative forms 
of the sv^itch may be applied to both the output and input file specifications. 
For example, the effect of the /EP switch applied to the output file can be 
overridden by applying the /-EP switch to a specific input file. 

The /-EP switch is useful for including modules that contain duplicate entry point names in the 
same library. The /-EP switch provides the means for entering a module in the library wdthout 
having its entry points included in the library EPT. 

The /-EP switch is also useful in the case where TKB uses only module names to search for 
modules in an object module library. In this case, entries in the library EPT are not required. 
The /-EP switch can be used to exclude entry points from being entered in the library EPT. 

Depending on whether the /EP switch is applied to the output specification or to an input 
specification, it has either a global or local effect. 

When applied to the output file specification, the /EP switch has a global effect. That is, LBR 
either includes all entry points in the EPT or excludes all entry points from being entered in 
the EPT. 

When applied to an input file specification, the /EP switch has a local effect. That is, LBR 
either includes entry points in the EPT or excludes entries from being entered in the EPT for 
only those modules to which the switch is applied. 

Entry points in an object module are not affected by the /EP switch. The switch only affects 
entries in the library EPT. 

10.3.2.7 Extract 

Use the Extract switch (/EX) to extract (read) one or more modules from an object or macro 
library file and write them into a specified output file. If more than one module is extracted, the 
modules are concatenated in the output file. The extract operation has no effect on the library 
file from which the modules are extracted; that file remains intact. Up to eight modules may 
be specified in one extract operation for object and macro libraries. However, only one module 
may be specified in one extract operation for a universal library. 

For object and macro libraries, if no modules are specified in the command line, all modules in 
the library are extracted and concatenated in the output file in alphabetical order. 

For universal libraries. Record Management Services (RMS) fields cannot be extracted to a 
record-oriented device, such as a terminal. 

The /EX switch may be applied only to input file specifications. 

Format 

outfile=infile/EX[:modulename[. . .]] 
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Parameters 

outflie 

Specifies the file specification into which extracted modules are to be stored. If the input 
modules are object modules, the default file type for this file is OBJ. If the input modiiles 
are macro modules, the default file type is MAC. If the library is a universal library, the 
outfile retains the infile type of the module extracted. (However, you are allowed to extract 
only one universal library module at a time.) 

inflle 

Specifies the library file specification from which the modules are to be extracted. The 
default file type for this file is ULB, OLD, or MLB, depending on the current default library 
type. 

modulename 

Specifies the name or names of the module or modules to be extracted from the library. 

Examples 

LBR>DRIVERS=RSX1 IM/EX : DXDRV : DKDRV : TTDRV [REt] 

Concatenates the object modules DXDRV, DKDRV, and TTDRV in alphabetical order and writes 
them into the file DRIVERS.OBJ. 

LBR>TI : = [1 . 1] RSXMAC . SML/EX : QIO$S [REH 

Writes the macro QIO$S to the issuing terminal. 

LBR>TEST . DBS=TEST/EX [RETI 

Writes all of the modules in the library TEST.OLB into the file TEST.OBS in alphabetical order. 

10.3.2.8 Insert Switch) for Object and Macro Libraries 

Use the Insert switch (/IN) to insert modules into a library file. Any number of input files can 
be specified. For object libraries and macro libraries, each input file can contain any number of 
concatenated input modules. For macro libraries, only first-level macro definitions are extracted 
from the input files. All text outside the first-level macro definitions is ignored. (The /IN switch 
for Universal Libraries, is explained in Section 10.3.2.9.) The /IN switch is the default library 
file option and can be appended only to the library file specification. 

If you attempt to insert an input module that already exists in the library file, the following 
message is printed on the initiating terminal: 

LBR — *FATAL* - Duplicate module name "name" in filename 

Likewise, if you attempt to insert a module and a module contains an entry point that duplicates 
one that is already in the EPT, the following message is printed on the initiating terminal: 

LBR — *FATAL* - Duplicate entry point "name" in filename 

Format 

outfile/IN=infile[,...] 
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Parameters 

outflle 

Specifies the library file specification into which the input modules are to be inserted. The 
default file type depends on the current default (see Section 10.3.2.4). It is OLB if the 
current default is object libraries, and it is MLB if the current default is macro libraries. 

inflle 

Specifies the input file specification containing the modules to be inserted into the library 
file. The default file type is OBJ if the outfile is an object library and MAC if the outfile is 
a macro library. 

Example 

LBR>RICKLIB/IN=SHEILA . LAURA . JENNY [RET] 

Inserts the modules contained in the latest versions of files SHEILA, LAURA, and JENNY, which 
reside in the default directory on SYO, into the latest version of the library file RICKLIB, which 
also resides in the default directory on SYO. The default file type for files SHEILA, LAURA, and 
JENNY is OBJ if RICKLIB is an object module library or MAC if RICKLIB is a macro library. 

1 0.3.2.9 Insert Switch! for Universal Libraries 

The Insert switch (/IN) works the same for universal libraries as it does for object libraries 
and macro libraries. However, when inserting a file into a universal library, the /IN switch is 
applied to the input file rather than the output file. You can also specify module name and 
descriptive information as switch values in the command line. In addition, LBR copies input 
file attributes to the module header. 

The high block indicator (F.HIBK of the file's descriptor block) and the end-of-file (EOF) indicator 
(F.EFBK of the file's File Descriptor Block (FDB)) are included in the input file's user file attributes. 
LBR makes the high block indicator equal to the EOF indicator in the module header. This 
means that when a module is extracted to a file, that file will have as many blocks allocated to 
it as are used. 

Format 

outfile=infile/IN:name[:op[. ..]] 

Parameters 

outfile 

Specifies the universal library file specification into which the infile is to be inserted. 

Inflle 

Specifies the input file specification to be inserted into the outfile. The default for the file 
type is the value indicated at the universal library's creation time. (See Section 10.3.2.2.) 

name 

Specifies the module name (up to six Radix-50 characters) optionally. The default is the 
first six characters of the input file name. 
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op 

Specifies optional descriptive information (up to six Radix-50 characters) to be stored in 
the module header. The default is null. If only part of the information set is specified, all 
preceding colons must be supplied. 

Example 

LBR>RICKLIB .ULB=JOE . TXT/IN : MODI : THIS : IS : JAN2 : TEXT \M] 

Inserts JOE.TXT into the universal library RICKLIB.ULB as MODI. THIS, IS, JAN2, and TEXT 
are stored in the module header. 

You can insert JOE.TXT without the /IN switch and its values. As a result, all the information 
normally specified by the switch values defaults as described in this example. 

10.3.2.10 List Switches 

Use the list switches (/LI, /LE, and /FU) to produce a printed listing of the contents of a library 
file. Three switches allow you to select the type of listing desired. The functions of these 
switches are as follows: 

/LI Lists the names of all modules in the library file. 

/LE Lists the names of all modules in the library file and their corresponding entry points. 

/FU Lists the names of all modules in the library file and gives a full module description for 
each; that is, size, date of insertion, and module-dependent information. 

These switches can be appended only to the output file specification or the Ust file specification. 

The /LI swdtch is the default value. It need not be specified when a listing file has been 
specified or when any other list switch is included in the command line. 

Format 

outfile[,listfile]/switch 

Parameters 

outfile 

Specifies the library file specification whose contents are to be listed. 

listflle 

Specifies the listing file specification optionally. If not specified, the listing is directed to the 
initiating terminal. 

switch 

Specifies the list option or options selected. 
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Examples 

LBR>RICKLIB/LI [RET] 

Prints a listing of the names of all the modules contained in file SYOrRICKLIB.OLB on the 
initiating terminal. 

lbr:*icklib/le [ret] 

Prints a listing of the names of all the modules and their entry points (contained in file 
SYO:RICKL1B.OLB) on the initiating terminal. 

LBR:«ICKLIB/FU [RET] 

Prints a listing of the names of all the modules in file SYOrRICKLIB.OLB and a full description 
of each module on the initiating terminal. 

LBR>«K 1 : [200 , 200] RICKLIB . LP . LST/LE/FU [RET] 

Creates file LP.LST in directory [200,200] on DKl, which lists the module names, their entry 
points, and a full description of each module for file RICKLIB. 

10.3.2.11 Modify Header 

The Modify Header switch (/MH) pertains only to universal libraries and allows you to modify 
the optional user-specified information in the module header. 

Format 

outfile/MH:module[:op[. . .]] 

Parameters 

outfile 

Specifies an output file specification for the universal library. The file type defaults to ULB. 

module 

Specifies the name of the module whose descriptive information is to be modified. 

op 

Specifies the optional user information (up to six Radix-50 characters) to be stored in the 
module header. The default is null and indicates that the corresponding information field is 
not to be changed. Also, entering a number sign (#) clears the corresponding information 
field. 

Example 

LBR«ICKLIB/MH : A : FCHTS : # : : [RET] 

Changes the optional descriptive information for module A of RICKLIB.ULB. 

The optional descriptive information for module A of RICKLIB.ULB was as follows: 

"MODA" "FCHCD" "OF" "FCH" 
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The previous command line changes the optional descriptive information for module A to the 
follov«ng: 

"FCHTS" " "OF" "FCH" 

10.3.2.12 Replace Switch for Macro and Object Libraries 

Use the Replace switch (/RP) to replace modules in a library file with input modules of the 
same name. Any number of input files are allowed and each file can contain any number of 
concatenated input modules. 

For macro libraries, only first-level macro definitions are extracted from the replacement files. 
LBR recognizes only uppercase letters in macro directives. 

When a match occurs on a module name, the existing module is logically deleted and all of its 
entries are removed from the EPT. 

As each module in the library file is replaced, a message is printed on the initiating terminal. 
This message, which contains the name of the module being replaced, is as follows: 

MODULE "name" REPLACED 

If the module to be replaced does not exist in the library file, LBR assumes that the input 
module is to be inserted and automatically inserts it without printing a message. 

The /RP switch can be specified in either of the following formats: 

Global format Appends the /RP switch to the library file specification. Assumes all of the 
input files contain replacement modules. 

Local format Appends the /RP switch to an input file specification. Considers only the file 
appended with the /RP switch contains replacement modules. 

Global Formot 

outfile/RP=infile[,...] 

Parameters 

outfile 

Specifies the library file specification. The default file type depends on the current default 
(see Section 10.3.2.4). It is OLB if the current default is object libraries or MLB if the current 
default is macro libraries. 

inflle 

Specifies the input file specification that contains replacement modules for the library file. 
The default tj^je is OBJ if outfile is an object library or MAC if it is a macro library. 

The global format allows you to specify a list of input files without having to append the /RP 
switch to each of them. 

To override the global function for a particular input file (that is, to instruct LBR to process a 
particular file in a list as a file containing modules to be inserted but not replaced), append the 
/-RP or /NORP switch to the desired input file specification. 
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Local Format 

outme=infile[/RP][,...] 

Parameters 

outfiie 

Specifies the library file spedfication. The local format default is the same as the global 
format default. 

inflle 

Specifies the input file specification that contains replacement modules for the output library 
file. The local format default is the same as the global format defauh. 

Appending the /RP switch to an input file specifier constitutes the local format of the switch. 
This overrides the LBR default (/IN) and instructs LBR to treat the module or modules contained 
in the specified file as replacement modules. 

Examples 

The output library file used in the following four examples contains the following object modules: 

Output Library File Object Modules 

RICKLIB.OLB;! JENNYl 

JENNY2 
LAURAl 
LAURA2 
SHEILA 

The input files used in the following four examples contain the modules listed as follows: 



Input File Object Modules 



SHEILA.OBJ;l 


SHEILA 


LAURA.OBJ;! 


LAURAl 




LAURA2 




LAURAS 


JENNY.OBJ;! 


JENNYl 




JENNY2 




JENNYS 


CHRIS.OBJ;l 


CHRISl 




CHRIS2 



These files are assumed to reside in the default directory on the default device and the initial 
state of the library file is assumed to be as shown previously. 
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1. The following command line uses the global format for the /RP switch. Object modules 
from the input files SHEILA, LAURA, and JENNY replace modules by the same riames in 
the library fUe named RICKLIB and modules JENNY3 and LAURA3 are inserted. 

LBH>RICKLIB/RP=SHEILA . LAURA . JENNY [RET] 

MODULE "SHEILA" REPLACED 

MODULE "LAURAl" REPLACED 

MODULE "LAURA2" REPLACED 

MODULE "JENNYl" REPLACED 

MODULE "JENNY2" REPLACED 

Produces the following library fUe: 

Output Library File Object Modules 

RICK.OLB;l JENNYl 

JENNY2 
JENNY3^ 
LAURAl 
LAURA2 
LAURAS^ 
SHEILA 

These modules did not exist in the library file prior to the execution of Example 1, but they did exist in the input files. LBR 
assumed they were to be inserted. Since LBR handled these modules as a normal insert, no message was printed on the input 
terminal. 

2. The following command line uses the local format of the /RP switch. The object module 
SHEILA from file SHEILA is replaced in the library file RICKLIB. The object modules in 
the file CHRIS are inserted in the library file. (See the description of the /IN switch in 
Section 10.3.2.8.) 

LBR>RICKLIB=CHRIS,SHEILA/RP [HI 

MODULE "SHEILA" REPLACED 

Produces the following library file: 



Output library file Object modules 



RICK.OLB;l CHRISl^ 

CHRIS21 
JENNYl 
JENNY2 
LAURAl 
LAURA2 
SHEILA^ 



2 
This module is replaced. 



The following command line uses the /-RP switch to override the global format of the 
command. Object modules in files SHEILA, LAURA, and JENNY are processed as modules 
to be replaced, and file CHRIS is processed as a file that contains modules to be inserted. 
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LBR>RICKLIB/RP=SHEILA . LAURA , JENNY . CHRIS/-RP [RET 

MODULE "SHEILA" REPLACED 
MODULE "LAURAl" REPLACED 
MODULE "LAURA2" REPLACED 
MODULE " JENNY 1" REPLACED 
MODULE "JENNY2" REPLACED 

Produces the following library file: 



Output Library File Object Modules 



RICKLIB.OLB;l CHRISl^ 

CHRISZ^ 
JENNYl 
JENNY2 
JENNYS^ 
LAURAl 
LAURA2 
LAURAS^ 
SHEILA 



These modules were specified to be inserted. If a module of the same name was present, a fatal error would have been issued 
(refer to Example 4). 

2t 



These modules were inserted by default. 



The following command line replaces module SHEILA from file SHEILA. The user specifies 
that the modules in file LAURA are not to be replaced (/NORP) but inserted. One of the 
modules contained in file LAURA duplicates an already existing module in file RICKLIB. 
Therefore, LBR issues the fatal error message and terminates the processing of the current 
command line. 

LBR>RICKLIB/RP=SHEILA , LAURA/NORP . JENNY \M] 

MODULE "SHEILA" REPLACED 

LBR — *FATAL* - Duplicate module "LAURAl" in LAURA. 0BJ;1 



10.3.2.13 Replace Switch for Universal Libraries 

Use the Replace switch (/RP) for universal libraries in the same way as for macro and object 
libraries. However, you can also specify the same values for the /RP switch as for the /IN 
switch for universal libraries (see Section 10.3.2.9). 

As with macro and object libraries, you can specify the /RP switch with either the output file 
specification or the input file specifications. 

Global Format 

outfile/RP:name[:op[...]]=infile[,...] 

Local Format 

outfile=infile/RP:name[:op[. . .]][, . . .] 
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Parameters 

outflie 

Specifies the universal library file specification. 

inflle 

Specifies the input file specification that contains replacement modules for the library file. 
The default for the file tj^e is the value indicated at the universal library's creation time. 
(See Section 10.3.2.2). 

name 

Specifies the module name to be replaced (up to six Radix-50 characters). The default is 
the first six characters of the infile name. 

op 

Specifies optional descriptive information (up to six Radix-50 characters) to be stored in 
the module header. The default is null. If only part of the information set is specified, all 
preceding colons must be supplied. 

Example 



Output Library File 


Modules 


TEXT.ULB;1 


DEBBIE 
BERNIE 


Shows the initial state of the library file. 


Input File 


Modules 


DEBBIE.TXT 



Shows the contents of the input file. 

LBR>TEXT . ULB=DEBBIE . TXT/RP : : THIS : IS : JAN3 : UPDATE [RET] 
MODULE "DEBBIE" REPLACED 

Replaces the module DEBBIE in the universal library TEXT.ULB with an updated module from 
file DEBBIE.TXT. The date of replacement is specified by the optional user information and is 
inserted in the module header. Note that the optional name is omitted. 

The resulting library file is as follows: 
Output library file Modules 



TEXT.ULB;1 DEBBIE^ 

BERNIE 



The module DEBBIE was replaced. If a different input file had been specified, that file would have become module DEBBIE and would 
have occupied the same location in TEXT.ULB. 
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10.3.2.14 Selective Search 

Use the Selective Search switch (/SS) to set the selective search attribute bit in the module 
header of object modules as they are inserted into an object library. The svdtch has no effect 
when applied to modules being inserted into a macro library. The sv^tch may be specified with 
input files for insertion or replacement operations only, and it affects all modules in the input 
file to which it is applied. 

Object modules with the selective search attribute are given special treatment by the Task 
Builder (TKB). Global S)rmbols, defined in modules with the selective search attribute, are 
included in TKB's symbol table only if they are previously referenced by other modules. 
Thus, only referenced sjmtibols will be listed with the module in TKB memory allocation file, 
thereby reducing task build time. The /SS switch should only be applied to object files whose 
modules contain only absolute (not relocatable) symbol definitions. See the RSX-llM-PLUS and 
Micro/RSX Task Builder Manual for more information. 

Format 

outfile=infile/SS[,...] 

Parameters 

outflle 

Specifies the library file specification. 

inflle 

Specifies the input file specification that contains modules to be selectively searched. 

Example 

LBR>ANGEL=JOHN , JILL/SS . MARK/SS , MARY [RETI 



Inserts the object files JOHN.OBJ, JILL.OBJ, MARK.OBJ, and MARY.OBJ into object library 
ANGEL.OLB. The selective search attribute bit is set in both the JILL and MARK object module 
header. 

10.3.2.15 Spool 

The Spool switch (/SP) is the list file default switch. Whether the switch is specified or not, 
the results are the same; that is, the listing file is spooled to the line printer. 

After the listing file is created, a request is made to the print spooler task to print the spooled 
file (see the RSX-llM-PLUS Batch and Queue Operations Manual for a description of the spooler 
task). 

The automatic printing of the listing file can be inhibited by specifying /-SP or /NOSP. This 
causes the listing file to be created, but the request to the print spooler task is not issued. 
Therefore, the file is not automatically printed. 

The /SP switch can orJy be appended to the list file specifier. 
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Format 

outfile,listfile/SP 

or 

outfile,listfile/-SP 

Parameters 

outflie 

Specifies the library file specification. 

listfile 

Specifies the listing file specification. 

Example 

LBR>RICKLIB/DE: SHEILA. RICKLST/-SP [M] 

Causes the following two actions: 

• Deletes the module SHEILA and its associated entry points from the library file SYrRICKUB. 

• Writes the listing of the contents of the resulting library file RICKLIB to the list file 
SYrRICKLST.LST. Because the /-SP switch is specified, the file is not automatically printed. 

10.3.2.16 Squeeze 

Use the Squeeze switch (/SZ) to reduce the size of macro definitions by eliminating all trailing 
blanks and tabs, blank lines, and comments from macro text. The /SZ switch is used to 
conserve memory in the MACRO-11 assembler and to reduce the size of macro library files. 
The /SZ switch has no effect on object libraries or universal libraries. 

The /SZ switch can be specified in either of the two following formats: 

Global format Appends the /SZ switch to the library file specification. Assumes all of the 
input files contain modules to be squeezed. 

Local format Appends the /SZ switch to an input file specification. The /SZ switch works 
only on the file to which you append it. 

Global Format 

outfile/SZ=infile[,...] 

Local Format 

outfile=infile/SZ[,...] 

Parameters 

outflie 

Specifies the library file specification. 
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infile 

Specifies the input file specification that contains modules to be squeezed during insertion 
into the library file. 

Use the global format of the /SZ switch to specify a list of input files without having to append 
the /SZ switch to each of them. To override the global function for a particular input file (that 
is, to instruct LBR to process a particular file in a list as a file containing modules to be inserted 
but not squeezed), append the /-SZ or /NOSZ switch to the desired input file specification. 

LBR uses the following algorithm on each line to be squeezed and then inserts the resulting 
line into the library file: 

1. The line is examined for the rightmost semicolon. 

2. If a semicolon is located, it is deleted, along with all trailing characters in the line. 

3. All trailing blanks and tabs in the line are deleted. 

4. If the resulting line is null, nothing is transferred to the library file. 

If the line contains a semicolon embedded in noncomment text and you want comments 
squeezed, code a dummy comment for that line. The /SZ switch will use only the rightmost 
comment during squeeze processing. 



Examples 












.MACRO 


MOVSTR 


RX.RY 


,?LBL 




;*** 


- - NOTE : 
BOTH ARGUMENTS 


MUST 


BE REGISTERS ; 




LBL: 


MOVE 

BNE 

DEC 


(RX)+. 

LBL 

RY 


(RY) + 


;MOVE A CHARACTER 
; CONTINUE UNTIL NULL 
; BACKUP OUTPUT PTR TO 


SEEN 
NULL 


;END 


OF MOVSTR 
.ENDM 










Shows the contents of the input file. 




;*** 
LBL: 


.MACRO MOVSTR 
- - NOTE : 
BOTH ARGUMENTS 
MOVB (RX)+, 
BNE LBL 
DEC RY 
.ENDM 


RX.RY 

MUST 
(RY) + 


,?LBL 

BE REGISTERS 





Shows the actual text inserted into the library file after the input file was squeezed by using 
the /SZ switch. 
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10.4 Combining Library Functions 

Two or more library functions may be requested in the same command line. The only exceptions 
are that the /CO switch cannot be specified with anything else except the /LI switch, and the 
/CR and /DE switches cannot be specified in the same command line. 

Functions are performed in the following order: 

1. Default switch (/DF) 

2. Create switch (/CR) 

3. Delete switch (/DE) 

4. Delete Global switch (/DG) 

5. Modify Header switch (/MH) 

6. Insert (/IN), Replace (/RP), Selective Search (/SS), Squeeze (/SZ), and Entry Point (/EP) 
switches 

7. Compress switch (/CO)) 

8. Extiract switch (/EX) 

9. Ust switches (/LI, /LE, and /FU) and Spool switch (/SP) 

Example 

LBR>FILE/DE ; XYZ : $A . LP . LST : /LE/FU=MODX , MODY/RP [RET] 
Performs the following functions in order: 

1. Deletes modules XYZ and $A. 

2. Inserts all modules from MODX and replaces duplicate modules of MODY. 

3. Produces a listing of the resultant library file on the line printer with full module descriptions 
and all entry points. 

1 0.5 LBR IS/lessages 

LBR returns two types of error messages: diagnostic and fatal. 

Diagnostic error messages describe a condition that requires consideration, but the nature of 
the condition does not warrant termination of the command. Diagnostic messages are issued to 
your terminal in the following format: 

LBR — *DIAG* - message 

Fatal error messages describe a condition that caused LBR to terminate the processing of a 
command. When this occurs, LBR returns to the highest level of command input. For example, 
if the command is entered in response to the Monitor Console Routine (MCR) prompt, LBR will 
issue the fatal error message, exit, and prompt you with the MCR prompt, as follows: 

>LBR conmandline 
LBR — message 
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If the command is entered in response to the LBR prompt, LBR will issue a fatal error message 
and prompt you with the LBR prompt, as follows: 

LBR>comBandliiie 
LBR — message 
LBR> 

Fatal error messages are issued to your terminal in the following format: 

LBR — *FATAL* - message 

If a fatal error occurs during the processing of an indirect command file, the command file 
is closed, the fatal error message — followed by the command line in error — is issued to your 
terminal, and LBR returns to the highest level of command input. 

10.5.1 LBR Diagnostic Error Messages 

The diagnostic error messages for LBR are as follows: 

LBR — 'DIAG* - Invalid operation for object and macro libraries 

Explanation: Module header information was supplied for an object library or macro library 
in an insert or replace operation. 

User Action: No user action is required. The command will be executed as if the information 
had not been supplied. 

LBR — -DIAG* - Mark for delete failure on LBR work tile 

Explanation: When LBR begins processing commands, it automatically creates a work file 
and marks it for deletion. For some reason, this marking for deletion failed. The work file 
constitutes a lost file because it does not appear in any file directory. 

User Action: The file may be deleted by running the File Structure Verification Utility (VFY). 
See Qiapter 14 for information on VFY. 

LBR — DIAG* - Multiple module extractions not permitted for UNI modules 

Explanation: An attempt was made to extract more than one module from a universal library. 
The first module specified is extracted, but others are ignored. 

User Action: Reenter the cortunand line for each additional extraction. 

LBR — 'DIAG* - Too many output files specified 

Explanation: More than two output files were specified. LBR makes the following 
assumptions: 

• The first output file specified is the output library file. 

• The second output file specified is the listing file. 

• The third through n files specified to the left of the equal sign are ignored. 

User Action: No user action is required. LBR continues as though the extra file or files had 
not been specified. 
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10.5.2 LBR Fatal Error Messages 

The status of a library file after fatal errors is as follows: 

1. In general, output errors leave the library in an indeterminate state. 

2. During the deletion process, the library is rewritten prior to the printing of the individual 
module-/entry-point-deleted messages. 

3. During the replacement process, the library is rewritten prior to the printing of the individual 
module-replaced messages. 

4. During the insertion process, the library is rewritten after the insertion of all modules in 
each individual input file, that is, between input files. 

The fatal error messages for LBR are as follows: 

LBR — -FATAL- - Bad library header 

Explanation: The file is not a library file or it is corrupted. 

User Action: If the file is not a library file, reenter the command line with a proper library 
file specified. 

If the file is a proper library file, you should run the File Structure Verification Utility (VFY) 
against the volume to determine if it is corrupted (see Chapter 14). 

If the volume is corrupted, it must be reconstructed before it can be used. 

LBR — -FATAL- - Cannot modify header 

Explanation: An attempt was made to modify the module header of a module in an object 
library or macro library. No change is made to the module header. 

User Action: Specify a module in a universal library and reenter the command line. 

LBR — -FATAL- - Command i/O error 

Explanation: One of the following conditions may exist: 

• A problem exists on the physical device (for example, it is not cycled up). 

• The file is corrupted or the format is incorrect (for example, record length exceeds 
132 bytes). 

User Action: Determine which of the conditions caused the message and correct that 
condition. Reenter the command line. 

LBR — -FATAL- - Command syntax error 
commandllne 

Explanation: A command was entered in a format that does not conform to syntax rules. 

User Action: Use the correct syntax and reenter the command line. 
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LBR — •FATAL' - Duplicate entry point name "name" in filename 

Explanation: An attempt was made to insert a module into a library file when both contain 
an identically named entry point. 

User Action: Determine if the specified input file is the correct file. If not, specify the correct 
input file and reenter the command line. If the input file is the correct file, you can delete 
the duplicate entry point from the library and reenter the command line. 

LBR — -FATAL* - Duplicate module name "name" in filename 

Explanation: An attempt was made to insert (without replacing) a module into a library that 
already contains a module with the specified name. 

User Action: Determine if the specified input file is the correct file. If the input file is correct, 
decide whether to delete the duplicate module from the library file and insert the new one, 
or replace the duplicate module with the /RP switch appended to the input file specification. 

LBR — FATAL* - EPT or MNT exceeded In filename 

Explanation: The EPT or MNT table limit was reached during the execution of an insert or 
replace operation. 

User Action: Copy the library and increase the table space by means of the /CO switch. 
Reenter the command line. 

LBR — FATAL* - EPT or IVINT space exceeded in compress 

Explanation: An EPT or MNT table size was specified for the output library file that is not 
large enough to contain the EPT or MNT entries used in the input library file. 

User Action: Reenter the command line with a larger EPT or MNT table size specified. 

LBR — 'FATAL* - Error In library tables, file filename 

Explanation: The library file is corrupted or is not a library file. 

User Action: If the file is corrupted, no recovery is possible; the file must be reconstructed. 
If the file is not a library file, reenter the command line with the correct library file specified. 

LBR — -FATAL* - Exactly one input file must appear witii /CO 

Explanation: No input library file, or more than one file, was specified when using the /CO 
switch. 

User Action: Reenter the command line with only one input file specified. 

LBR — FATAL* - Fatal compress error 

Explanation: The input library file is corrupted or is not a library file. 

User Action: No recovery is possible. The file in question must be reconstructed. 
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LBR — FATAL- - Get time failed 

Explanation: This error occurs when LBR attempts to execute a Get Time Parameters directive 
arid fails. The error is caused by a system malfunction. 

User Action: Reenter the command line. If the problem persists, submit a Software 
Performance Report (SPR) along with the related console dialog and any other pertinent 
information. 

LBR — FATAL* - liiegoi device/voiume 
commandiine 

Explanation: The device specifier entered does not conform to syntax rules. A device specifier 
consists of two American Standard Code for Information Interchange (ASCII) characters, 
followed by one or two optional octal digits. 

User Action: Reenter the command line with the correct device syntax specified and followed 
by a colon ( : ). 

LBR — FATAL- - iliegal directory 
commandiine 

Explanation: The directory entered does not conform to syntax rules. Proper directory syntax 
consists of a left square bracket ([), followed by one to three octal digits, a comma, and 
one to three octal digits, which terminates by a right square bracket ( ] ), or it may consist 
of a named directory, which contains one to nine characters enclosed in brackets. 

User Action: Reenter the command line with the correct directory syntax. 

LBR — -FATAL- - iliegai filename 
commandiine 

Explanation: One of the following was entered: 

• A file specifier that contained a wildcard. 

• A file specifier that contained neither a file name nor a file type. 
User Action: Reenter the command line correctly. 

LBR — -FATAL- - Illegal get command line error code 

Explanation: The system, for some reason, is unable to read a command line. This is an 
internal system failure. 

User Action: Reenter the command line. If the problem persists, submit an SPR along with 
the related console dialog and any other pertinent information. 

LBR — FATAL- - Illegal switch 
commandiine 

Explanation: A non-LBR switch was specified or a legal switch was specified in an invalid 
context. 

User Action: Reenter the command line with the correct switch specification. 
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LBR — 'FATAL* - Illegal switch combination 

Explanation: Switches were entered that cannot be executed in combination (see 
Section 10.4). 

User Action: Specify the switches in the proper combination and reenter the command line. 

LBR — "FATAL* - Indirect command syntax error 
commandline 

Explanation: An indirect command file was specified in a format that does not conform to 
syntax rules. 

User Action: Reenter the command line with the correct syntax. 

LBR — FATAL* - Indirect file deptli exceeded 
commandline 

Explanation: An attempt was made to exceed one level of indirect command files. 

User Action: Rerun the job with only one level of indirect command file specified. 

LBR — *FATAL* - indirect tile open failure 
commandline 

Explanation: The requested indirect command file does not exist as specified. One of the 
bllowing conditions may exist: 

The user directory area is protected against access. 

A problem exists on the physical device (for example, device cycled down). 

The volume is not mounted. 

The specified file directory does not exist. 

The file does not exist as specified. 

There is insufficient dynamic memory in the Executive. 

User Action: Determine which of the conditions caused the message and correct that 
condition. Reenter the command line. 

LBR — *FATAL* - input error on filename 

Explanation: The file system, while attempting to process an input file, has detected an error. 
A problem exists with the physical device (for example, the device cycled down). 

User Action: Find and fix the problem, and reenter the command line. 

LBR — *FATAL* - insufflcient dynamic memory to continue 

Explanation: The partition in which LBR is running is too small for the task size. 

User Action: Remove the task (LBR), install it in a larger partition, and reenter the command 
line. (See the descriptions of the INSTALL command in the RSX-llM-PLUS Command 
Language Manual and RSX-llM-PLUS MCR Operations Manual.) 
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LBR — FATAL- - Invalid EPT and/or MNT specification 

Explanation: An EPT or MNT value greater than 4096io was entered with the /CR or /CO 
switch. 

User Action: Reenter the command line with the correct value specified. 

LBR — FATAL- - invalid (lietype 

Explanation: The specified file type contained illegal RAD50 characters. 
User Action: Specify a valid file type and reenter the command line. 

LBR — -FATAL- ■ invalid format, Input file filename 

Explanation: The format of the specified input file is not the standard format for a macro 
source or object file, or the input file is corrupted. 

User Action: Reenter the command line with the correct input file specified. 

LBR — -FATAL- - invalid library type specified 

Explanation: An invalid library type was specified when using the /CR or /DF switch. 
The values OBJ, MAC, and UNI are the only valid specifications. See Sections 10.3.2.2 
and 10.3.2.4. 

User Action: Reenter the command line with OBJ, MAC, or UNI specified. 

LBR — -FATAL- - invalid module format in insertion module 

Explanation: An attempt was made to insert a macro module into an object library. 

User Action: Determine if an object file was to be inserted into an object library. If so, 
reenter the command line vnth the correct object file. If a macro library was to receive the 
insertion, reenter the command line with the correct macro library. 

LBR — -FATAL- - Invalid name "name" 

Explanation: A module name that contains a non-Radix-50 character was specified for 
deletion, insertion, or replacement of a module in a universal library or in a macro module; 
or a module name was specified for modification of a universal module header. Radix-50 
characters consist of the letters A to Z, the numbers to 9, and the special characters period 
( . ) and dollar sign ( $ ). 

User Action: Reenter the command line and specify a valid name. 

LBR — -FATAL- - Invalid RAD50 character In "character string" 

Explanation: A character supplied as part of information when using the /IN, /RP, or /MH 
switch for a universal library is not a Radix-50 character. 

User Action: Determine which character of the corresponding switch value is not a Radix-50 
character. Reenter a Radix-50 character in place of the invalid character. 
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LBR — 'FATAL* - I/O error on input file filename 

Explanation: A read error has occurred on an input file. One of the following conditions 
may exist: 

• A problem exists on the physical device (for example, it is not cycled up). 

• The file is corrupted or the format is wrong (record length exceeds 132 bytes). 

User Action: Determine which of the conditions caused the message and correct that 
condition. Reenter the command line. 

LBR — •FATAL- - Library file specification missing 

Explanation: A command line was entered without specifying the library file. 
User Action: Reenter the command line with the library file specified. 

LBR — *FATAL> - Missing output file specifier 

Explanation: The command line was issued without the output file specification. 
User Action: Specify the output file and reenter the command line. 

LBR — 'FATAL- - No entry point named "name" 

Explanation: The entry point to be deleted is not in the specified library file. 

User Action: Determine if the entry point is misspelled or if the wrong library file is specified. 
Reenter the command line with the entry point or the library file correctly specified. 

LBR — 'FATAL' - No module named "module" 

Explanation: The module to be deleted is not in the specified library file. 

User Action: Determine if the module name is misspelled or if the wrong library file is 
specified. Reenter the command line with the module name correctly specified. 

LBR — 'FATAL' - Open failure on file filename 

Explanation: The file system, while attempting to open a file, has detected an error. One of 
the following conditions may exist: 

The user directory area is protected against operung a file. 

A problem exists on the physical device (for example, device cycled down). 

The volume is not mounted. 

The specified file directory does not exist. 

The file does not exist as specified. 

There is insufficient contiguous space to allocate the library file (see the /CO and /CR 
switches). 

There is insufficient dynamic memory in the Executive. 

User Action: Determine which of the above conditions caused the message and correct that 
condition. Reenter the command Une. 
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LBR — -FATAL- - Open failure on LBR work file 

Explanation: The fQe system, while attempting to open the LBR work file, has detected an 
error. The LBR work file is created on the volume from which LBR was installed. One of 
the following conditions may exist: 

• The volume is full. 

• The device is write-protected. 

• A problem exists with the physical device. 

• Insufficient dynamic memory exists in the Executive. 

User Action: Determine which of the conditions caused the message and correct that 
condition. Reenter the command line. 

LBR — -FATAL- - Output error on filename 

Explanation: A write error has occurred on the output file. One of the following conditions 
may exist: 

• The volume is full. 

• The device is write-protected. 

• The hardware has failed. 

User Action: If the volume is full, delete all unnecessary files and rerun LBR. If the device 
is write-protected, write-enable the device and reenter the command line. If the hardware 
has failed, swap devices and reenter the command line or wait until the device is repaired 
and rerun LBR. 

LBR — -FATAL- - Privilege violation on file filename 

Explanation: LBR was unable to open file because of privilege violations. 
User Action: Reset privileges and reenter the command line. 

LBR — -FATAL- - Positioning error on filename 

Explanation: A positioning error has occurred on the input file. One of the following 
conditions exist: 

• A problem exists on the physical device (for example, it is not cycled up). 

• The file is corrupted or the format is wrong. 

User Action: Determine which of the conditions caused the message and correct that 
condition. Reenter the command line. 

LBR — FATAL- - RMS module cannot be extracted to record oriented devices 

Explanation: An attempt was made to extract a module inserted from a nonsequential RMS 
file to a record-oriented device. This is a fatal error message. 

User Action: Extract the file to a disk and then use an RMS conversion to make an RMS 
sequential file. 
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LBR — -FATAL- - Too mony input flies 

Explanation: The LBR switch /EX was used with more than one input file. 

User Action: Specify one input file with the /EX switch and reenter the command line. 

LBR — -FATAL- - Virtual storage requirement exceeds 65536. words 

Explanation: This error may occur if you are working with maximum size libraries and you 
specify a single command line that first logically deletes a large number of modules and 
entry points, and then replaces them with an equally large number of modules and entry 
points that have names much different from those being replaced. Normally, this message 
indicates some sort of internal system error. 

User Action: Rerun the job, but divide the complicated command line into several smaller 
command lines that do the same operations. 

LBR — FATAL- - Work file I/O error 

Explanation: A write error has occurred on the LBR work file. One of the following 
conditions may exist: 

• The volume is full. 

• The device is write-protected. 

• The hardware has failed. 

User Action: If the volume is full, delete all unnecessary files and rerun LBR. If the device 
is write-protected, write-enable the device and reenter the command line. If the hardware 
has failed, swap devices and retry the command, or wait until the device is repaired and 
rerun LBR. 
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Chapter 1 1 



Object Module Patch Utility (PAT) 



The Object Module Patch UtiHty (PAT) allows you to update, or patch, code in a relocatable 
binary object module. 

Input to PAT is two files: an input file and a correction file. The input file consists of one or 
more concatenated object modules. You can correct only one of these object modules with a 
single execution of PAT. The correction file consists of object code that, when linked by the 
Task Builder (TKB), either overlays or is appended to the input object module. Unlike TKB and 
ZAP patching options, PAT allows you to increase the size of the object module because the 
changes are applied before the module is linked by TKB. 

PAT uses the correction file, which contains corrections and/or additional instructions, to update 
the object module. Correction input is prepared in source form and then assembled by the 
MACRO-11 assembler. 

Output from PAT is the updated input file. 

11.1 PAT Command Line 

You invoke PAT by using any of the methods for invoking a utility, as described in Chapter 1. 
PAT can be used interactively or by means of indirect command files. If you use indirect 
command files, PAT allows a maximum nesting level of 2. 

The command line for PAT is shown next. 

Format 

[outfiIe]=infile[/CS[:n]],conrectfiIe[/CS:[n]] 

Parameters 

outflle 

Specifies the file specification for the output file. The format for entering file specifications 
is as follows: 

ddsn : [directory] filename . type ; version 

Refer to Chapter 1 for detailed descriptions of the parameters for file specifications. 
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If you do not specify an output file, PAT does not generate one. 

Inflle 

Specifies the file specification for the input file. This file can contain one or more 
concatenated object modules. 

correctflle 

Specifies the file specification for the correction file. This file contains the updates to be 
applied to one module in the input file. 

/CS[:n] 

Specifies the Checksum switch. This switch directs PAT to calculate the checksum for all 
the binary data that constitutes the module. PAT displays this checksum in octal. (Refer to 
Section 11.2.4 for information on how to use the /CS switch.) You can optionally specify 
an octal number, n, with the /CS switch. Then, after PAT calculates the checksum value, it 
compares that value with the number specified. If the values are not the same, PAT informs 
you with an error message. You must then rerun PAT with the correct checksum specified. 

Using PAT to update a file involves several steps. First, you create the correction file by using 
a text editor. Once created, the correction file must be assembled to produce an object module. 
The correction file and the input file (both in object module format) are then submitted to PAT 
for processing. Finally, the updated input object module is submitted to TKB to resolve global 
symbols and to create an executable task. Figure 11-1 shows the steps involved in using PAT 
to generate an updated task file. 
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Figure 11-1: Processing Steps Required to Update a IVIoduie Using PAT 




1 . Generate a correction file using 
the Text Editor. 



CORRECT.SRC 



c> 



CORRECT.SRC 



^ 



2. Execute the assembler (or compiler) 
to generate an object module 
version of the file. 



CORRECT.OBJ 



C> 



CORRECT.OBJ 



MYFILE.OBJ 



^ 



3. Execute PAT using as input the 
correction file and the module to 
be updated. 



MYFILE.OBJ 



c> 




4. Execute the Task Builder to 
resolve new addresses and 
generate an executable task. 



MYFILE TSK 



C> 



ZK-1 99-81 



1 1 .2 How PAT Applies Updates 

This section describes the PAT input and correction files, gives information on how to create 
the correction file, and provides examples of how PAT applies the corrections to a modtile. 
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11.2.1 Input File 

The input file is the file to be updated; it is the base for the output file. The input file must 
be in object module fonnat. When you execute PAT, the correction file is applied to one of the 
object modules in the file. PAT assumes a file type of OBJ for the input file. If you use a file 
type other than OBJ, you must specify it explicitly in the command line. 

11.2.2 Correction File 

The correction file contains the patches to be applied to the input file. PAT assumes a file type 
of OBJ for the correction file. If you use a file type other than OBJ, you must specify it explicitiy 
in the command line. 

As shown in Figure 11-1, the first step in using PAT to update an object file is to generate the 
correction file. Use any text editor to create this source file. 

Format 

.TITLE inputname 
.IDENT updatenum 
inputline 
inputline 



Parameters 

inputname 

Specifies the name of the module to be corrected by the PAT update. You must specify the 
module that you are updating for inputname. 

updatenum 

Specifies any value acceptable to the MACRO-11 assembler .IDENT directive. Generally, 
this value reflects the updated version of the file to be processed by PAT (as shown in the 
example provided in Sections 11.2.3.1 and 11.2.3.2). 

Note 

The .IDENT assembler directive is a required part of the correction file. 
Failure to include an .IDENT assembler directive in the file produces 
unusable output. 

Inputline 

Specifies lines of input to be used to correct and update the input file. 
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Once you have created the source version of the correction file, you assemble it to produce an 
object module that can be processed by PAT. 

During PAT execution, new global symbols defined in the correction file are added to the 
modtile's symbol table. A symbol definition that is already being used in the input file can be 
superseded by the definition in the correction file. For a symbol definition to be superseded, 
both definitions must be either relocatable or absolute. 

A duplicate program section supersedes the previous program section if the following conditions 
are met: 

• Both have the same relocatability attribute (ABS or REL) 

• Both are defined with the same directive (.PSECT or .CSECT) 

If PAT encounters duplicate program section names, the length attribute for the program section 
is set to the length of the longer program section and a new program section is appended to 
the module. 

If you specify a transfer address, it supersedes the transfer address of the module being patched. 

1 1.2.3 How PAT and the Task Builder Update Object Modules 

The examples in the following sections show an input file and a correction file (both in object 
module format) to be processed by PAT and TKB, along with a source-like representation of how 
the output file looks once PAT and TKB complete processing. Two techniques are described: 
one for overlaying lines in a module and the other for adding a subroutine to a module. 

11.2.3.1 Overlaying Lines in a IVIodule 

The following example illustrates a technique using a patch file to overlay lines in a module. 
First, PAT appends the correction file to the input file. Then, TKB generates a task image from 
the patched object modules. 

The following file is the input file: 

.TITLE ABC 

. IDENT /Ol/ 

ABC:: 

MOV A,C 

CALL XYZ 

RETURN 

.END 

To add the ADD A,B instruction after the CALL instruction, you can use the following patch in 
the correction file: 

.TITLE ABC 

.IDENT /Ol.Ol/ 

.=.+12 

ADD A.B 

RETURN 

.END 
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You use the MACRO- 11 assembler to assemble the correction file. After assembly, PAT processes 
the resulting object module and the input object module. The result of PAT processing appears 
as follows: 



.TITLE 


ABC 


.IDENT 


/Ol.Ol/ 


ABC: : 




MOV 


A.C 


CAT.T, 


XYZ 


RETUHN 




.=ABC 




.=.+12 




ADD 


A.B 


RETURN 




.END 





You then use TKB to produce the patched object module as a task image. This task image looks 
the same as the source code would have looked if it had originally been written as follows: 



.TITLE 


ABC 


.IDENT 


/Ol.Ol/ 


ABC:: 




MOV 


A.C 


CALL 


XYZ 


ADD 


A.B 


RETURN 




-END 





PAT uses ".=.+12" in the program counter field to determine where to begin overlaying 
instructions in the program. It overlays the RETURN instruction vnth the following patch 
code: 

ADD A.B 

RETURN 

1 1.2.3.2 Adding a Subroutine to a IVIoduie 

The following example illustrates a technique for adding a subroutine to an object module. A 
patch often requires that more than a few lines be added to correct the file. A convenient 
technique for adding new code is to append it to the end of the module as a subroutine. That 
way, you insert a CALL instruction at an appropriate location in the subroutine. The CALL 
instruction directs the program to branch to the new code, to execute that code, and then to 
return to inline processing. 

The input file is as follows: 



.TITLE 


ABC 


. IDENT 


/Ol/ 


ABC:: 




MOV 


A.B 


CALL 


XYZ 


MOV 


C.RO 


RETURN 





.END 
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The correction file for this example is as follows: 



.TITLE 


ABC 


.IDENT 


/Ol.Ol/ 


CALL 


PAl-CH 


NOP 




.PSECT 


PATCH 


PATCH: 




MOV 


A.B 


MOV 


D.RO 


ASL 


RO 


RETURN 




.END 





PAT merges the correction file with the input file, as shown in the example in Section 11.2.3.1. 
TKB then processes the files and produces a task image that looks the same as the source file 
would have looked if it had originally been written as follows: 



.TITLE 


ABC 


.IDENT 


/Ol.Ol/ 


ABC:: 




CALL 


PATCH 


NOP 




CALL 


XYZ 


MOV 


C.RO 


RETURN 




.PSECT 


PATCH 


PATCH: 




MOV 


A.B 


MOV 


D.RO 


ASL 


RO 


RETURN 




.END 





In this example, the CALL PATCH and NOP instructions overlay the 3-word MOV A,B 
instruction. (The NOP instruction is included because this is a case where a 2-word instruction 
replaces a 3-word instruction and the NOP instruction is required to maintain alignment.) TKB 
allocates additional storage for .PSECT PATCH, writes the specified code into this program 
section, and binds the CALL instruction to the first address in this section. The MOV A,B 
instruction, replaced by the CALL PATCH instruction, is the first instruction executed by the 
PATCH subroutine. 



Object Module Patch Utility (PAT) 11-7 



1 1.2.4 Determining and Validating ttie Contents of a File 

You use the Checksum switch (/CS) to determine or validate the contents of a module. The 
switch directs PAT to calculate the checksum (in octal) for all the binary data that constitutes 
the module and to then inform you of the checksum by means of a diagnostic message. 

To determine the checksum of a file, enter the PAT command line with the /CS switch applied 
to that file's specification, as follows: 

=MYFILE/CS . CORRECT . FOB 

The command directs PAT to calculate the checksum for the input file; MYFILE.PAT then 
responds with the following message: 

PAT — Input module checksum is checksum 

PAT generates a similar message when you request the checksum for the correction file, as 
follows: 

=MYFILE . CORRECT . POB/CS 

After calculating the checksum for the correction file, PAT responds with the following message: 

PAT — Correction input file checksum is checksum 

If you specify /CS:n to validate the size of a file, PAT calculates the checksum for the file and 
then compares that checksum with the value, n, you specified. If the two values do not match, 
PAT displays the foUovdng message to report the checksum error: 

PAT -- Error in file filename checksum 

You might specify the following change: 

=MYFILE . CORRECT . POB/CS : 432163 

When PAT calculates the checksum for the correction file, the number is different. PAT then 
displays the following message: 

PAT — Error in file CORRECT. POB checksum 

Checksum processing always results in an octal, nonzero value. 

1 1.3 PAT IVIessages 

PAT generates messages that state checksum values and messages that describe error conditions. 
For diagnostic error messages, PAT prefixes the messages with the following: 

PAT -- *DIAG*- message 

For fatal error messages, PAT uses the following prefix: 

PAT -- *FATAL*- message 

Fatal and diagnostic error messages describe a condition that caused PAT to terminate the 
processing of a command. When this occurs, PAT returns to the highest level of command 
input. For example, if the command is entered in response to the Monitor Console Routine 
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(MCR) prompt, PAT will issue the error message, exit, and prompt you with the MCR prompt, 
as follows: 

>PAT commandline 
PAT — message 
> 

If the command is entered in response to the PAT prompt, PAT will issue the error message 
and prompt you with the PAT prompt, as follows: 

PAT>coiimiandllne 
PAT — message 
PAT> 

If an error occurs during the processing of an indirect command file, the command file is closed, 
the error message — followed by the command line in error — is issued to your terminal, and 
PAT returns to the highest level of command input. 

11.3.1 Informational Messages 

The following messages describe results of checksum processing: 

PAT — Correction input file checicsum Is checlcsum 

Explanation: When you specify the /CS switch in the correction file specification, PAT 
informs you of the file's checksum value. The value is given in octal. 

User Action: No user action is required. 

PAT — input moduie checksum is cliecksum 

Explanation: When you specify the /CS switch in the input file specification, PAT informs 
you of the file's checksum value. The value is given in octal. 

User Action: No user action is required. 

1 1.3.2 Error Messages 

The following error messages are issued by PAT: 

PAT — Command iine error 
commandline 

Explanation: The system standard conunand line processor (.GCML) detected an error in the 
command line. 

User Action: Use the correct information and reenter the command line. 

PAT — Command syntax error 
commandline 

Explanation: The command line contained a syntax error. 

User Action: Use the correct syntax and reenter the command line. 
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PAT — Correction Input file missing 
commandllne 

Explanation: The mandatory correction file was not specified. 

User Action: Specify the correction file and reenter the command line. 

PAT — Error during close: (lie: 
filename 

Explanation: This error is most likely to occur while PAT is attempting to write the remaining 
data into the output file before deaccessing it. The most likely causes of this error are the 
following conditions: 

• The device is full. 

• The device is write-locked. 

• A hardware error occurred. 

User Action: Perform the appropriate corrective action and reenter the command line: if the 
device is full, delete all unnecessary files; if the device is write-locked, write-enable it; if the 
problem is a hardware error, contact your DIGITAL Field Service representative. 

PAT — Error in file filename checlcsum 

Explanation: The checksum that PAT calculated for the named file. 

User Action: Ensure that you specified the correct checksum. If the checksum is correct, 
then you specified an invalid version of the file. Rerun PAT with the correct version of the 
file specified. 

PAT — Error positioning file 
filename 

Explanation: PAT attempted to position the file beyond end-of-file (EOF). 

User Action: Submit a Software Performance Report (SPR) along with the related console 
dialog and any other pertinent information. 

PAT — File filename has Illegal format 

Explanation: The format of the named file is not compatible with the object files produced 
by the standard DIGITAL language processors or accepted by TKB. The principal causes are 
as follows: 

• Truncated input file 

• Input file that consists of text 

User Action: Ensure that the file is in the correct format and resubmit it for PAT processing. 

PAT — illegal device/volume specified 
devlcename 

Explanation: The device or volume name specification contained a syntax error. 

User Action: Check the rules for specifying devices and volumes; then, use the correct syntax 
for the device or volume specification and reenter the command line. 
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PAT — Illegal directory speclflcatlon 
directoryname 

Explanation: The directory specification contained a syntax error. 

User Action: Check the rules for specifying a directory; then, use the correct syntax for the 
directory specification and reenter the command Une. 

PAT — Illegal error-severity code 
errordata 

Explanation: An error message call, containing an illegal parameter, has been generated. 

User Action: If these messages persist, submit an SPR along with related console dialog and 
any other pertinent information. 

PAT — Illegal file speclflcatlon 
filename 

Explanation: The file specification contained a syntax error. 

User Action: Use the correct syntax for the file specification and reenter the command line. 

PAT — Illegal Indirect file speclflcatlon 
commandline 

Explanation: You specified an indirect command file that contains one of the following errors: 

• A syntax error 

• A specification for a nonexistent indirect command file 

User Action: Check for file specification syntax errors or ensure that the specified file is 
contained in the specified directory; then, reenter the command line. 

PAT — Illegal switch) specified 
filename 

Explanation: An unrecognized switch or switch value was specified with the file. 

User Action: Check the rules for specifying the switch, use the correct switch or switch 
value, and reenter the command line. 

PAT — Incompatible reference to global symbol 
symbolnome 

Explanation: The correction file contains a global symbol whose attributes do not match one 
or more of the following input file S3mibol attributes: 

• Definition or reference 

• Relocatable or absolute 

User Action: Update the correction file by modifying the symbol attributes. Reassemble the 
file and resubmit it for PAT processing. 
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PAT — Incompatible reference to program section 
sectionname 

Explanation: The correction file contains a section name whose attributes do not match one 
or both of the following input file section attributes: 

• Relocatable or absolute 

• Defined with the same directive (.PSECT or .CSECT) 

User Action: Update the correction file by modifying the section attribute or by changing 
the section type. Reassemble the file and resubmit it to PAT for processing. 

PAT — I/O error on input die 
filename 

Explanation: An error was detected while PAT was attempting to read the specified input 
file. The principal cause of this error is a device hardware error. 

User Action: Reenter the command. 

PAT — I/O error on output flie 
filename 

Explanation: An error occurred while PAT attempted to write into the named output file. 
The most likely causes of this error are the following conditions: 

• The device is full. 

• The device is write-locked. 

• A device hardware error occurred. 

User Action: Perform the appropriate corrective action and reenter the command line: if the 
device is full, delete all unnecessary files; if the device is write-locked, write-enable it; if the 
problem is a hardware error, contact your DIGITAL Field Service representative. 

PAT — Invalid file specified: 
filename 

Explanation: You specified a file that contains one of the following errors: 

• Nonexistent device 

• Nonexistent directory — The directory in the file name specification does not exist on the 
specified device (or on the default device if no device was specified). 

User Action: Specify the correct device or directory, and reenter the command line. 

PAT — Maximum Indirect file depth exceeded 
commandline 

Explanation: In the command line, you specified an indirect command file that exceeds the 
maximum nesting level of 2 that is permitted by PAT. 

User Action: Reorder your files so that they do not exceed PAT's nesting limit. 
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PAT — Multiple output files specified 
commandline 

Explanation: PAT accepts only one output file specification. 

User Action: Specify only one output file and reenter the command line. 

PAT — No dynamic storage available 
storage llsthead 

Explanation: Not enough contiguous task memory was available to satisfy a request for the 
allocation of storage. PAT displays the contents of the 2-word dynamic storage llsthead in 
octal. 

User Action: If possible, PAT should be reinstalled with a larger increment or in a bigger 
partition. (See the description of the Monitor Console Routine (MCR) or the DIGITAL 
Command Language (DCL) command INSTALL in the RSX-llM-PLUS MCR Operations 
Manual or RSX-llM-PLUS Command Language Manual.) 

PAT — Required Input file missing 
commandline 

Explanation: The mandatory input file was not specified in the command line. 

User Action: Specify an input file and reenter the command line. 

PAT — Symbol "symbol" Is multiply defined 

Explanation: You have tried to define a symbol that was previously defined. 
User Action: Define a different symbol. 

PAT — Too many input files specified 
commandline 

Explanation: Too many input files were specified in the command line. PAT accepts only 
the input and correction file specifications. 

User Action: Specify the correct files and reenter the command line. 

PAT— Unable to find file 
filename 

Explanation: PAT could not locate the specified input or correction file. 

User Action: Check the directory to ensure that the file exists, specify the correct file name, 
and reenter the command line. 

PAT — Unable to locate module 
moduiename 

Explanation: PAT could not find the module name that was specified in the correction file 
in the file of concatenated input modules. 

User Action: Update the input file specification to include the missing module. Reenter the 
command line. 
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PAT — Unable to open file 
filename 

Explanation: There is insufficient workspace in the internal File Storage Region (FSR) of the 
PAT utility. 

User Action: If possible, PAT should be reinstalled with a larger increment or in a bigger 
partition. (See the description of the Monitor Console Routine (MCR) or the DIGITAL 
Command Language (DCL) command INSTALL in the RSX-llM-PLUS MCR Operations 
Manual or RSX-llM-PLUS Command Language Manual.) 
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Chapter 12 



Peripheral Interchange Program (PIP) 



The Peripheral Interchange Program (PIP) is a file utility program that transfers data files from 
one standard Files-1 1 device to another. PIP also performs file control functions. Some of the 
functions PIP performs are as follows: 

Copying files from one device to another 

Deleting files 

Renaming files 

Listing file directories 

Setting the default device and User Identification Code (UIC) for PIP operations 

Unlocking files 

Spooling files 

12.1 PIP Command Line 

You can invoke the PIP utility by using any of the methods described in Chapter 1. You invoke 
PIP file control functions by means of switches and subswitches. 

You request PIP functions by entering PIP command lines through the initiating terminal or by 
means of an indirect command file. The maximum nesting level for indirect command files is 
four. (See Chapter 1 for more information on using indirect command files.) 

The MCR command line for PIP differs for each function. Therefore, the command line formats 
are described in separate sections. 
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12.1.1 PIP Defaults for File Specification Elements 

With the exception of the version number, PIP generally uses the last value encountered in the 
command line as the default. That is, PIP uses values you enter to set defaults and changes 
the default when you change the value. Exceptions to this are noted in the descriptions of each 
switch. 

The format for entering file specifications is shown next. 

Format 

ddnn:[directory]filename.type;version[[/switch][...][/subswitch]] 
Refer to Chapter 1 for detailed descriptions of the parameters for file specifications. 

Example 

p}p>Tl . MAC ; 5 , T2 , . TSK/BR [RET] 

T1.MAC;5 
T2.MAC;1 
T2.TSK;3 

Causes T1.MAC;5 to set the defaults for the subsequent file specifications in the command 
line. Then, T2 is specified and overrides Tl as the default file name; however, MAC remains 
the default file type. Finally, TSK is specified, which overrides MAC as the default, while T2 
remains the default file name. 

Note, in this example, that the version number does not default. 

Table 12-1 summarizes the rules PIP uses to set defaults. 

Table 12-1: PIP Default File Specifications 



Element 



Default Value 



ddnn For the first file specification, the unit on which the user's system disk is 

mounted (SYO) or the default that you specify with the Default sv«tch (/DF) 
(see Section 12.1.4.6). For subsequent file specifications, either you explicitly 
specify a new device or PIP assumes the device from the previous specification. 

directory For the first file specification, your current directory (that is, the directory under 

which you log in), the directory you specify witt\ the SET command, or the 
default you specify with the /DF switch (see Section 12.1.4.6). For subsequent 
file specifications, either you explicitly specify a new directory or PIP assumes 
the directory from the previous specification. Only the asterisk (♦) is valid as a 
v«ldcard (see Section 12.1.3). 

filename No default for the first file specification. For subsequent file specifications, it is 

the last file name that you explicitly specified. Asterisks ( * ) and/or percent signs 
(%) are valid as v^ldcards (see Section 12.1.3). 

type No default for the first file specification. For subsequent file specifications, it is 

the last file tj^e that you explicitly specified. Asterisks ( * ) and/or percent signs 
(%) are valid as wildcards (see Section 12.1.3). 
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Table 12-1 (Cont.): PIP Default File Specifications 



Element Default Value 



version The default for mput files is the most recent version number. The default for 

output files is the next higher version number, or it is version 1 if the file does 
not exist in the output directory. An exception is the PIP file delete function, 
which requires that a version number be specified. 

An explicit version number is defined to be of the form ;n where n is greater than 
0. A version number of ;-l may be used to specify the oldest version of a file. 
A version number of ;0 or ; may be specified to signify the most recent version. 
In certain cases, just the asterisk (wildcard) may be specified, as described in 
Section 12.1.3. 

12.1.2 Using PIP File Control Switclies and Subswitches 

PIP provides several file control switches and subswitches. A switch specification consists of a 
slash (/) followed by a 2- or 3-character switch name. The switch specification is optionally 
followed by a subswitch name separated from the switch name by a slash. The switch or 
subswitch can have arguments that are separated from the switch or subswitch name by a 
colon ( : ). 

To allow several commands to be performed consecutively, more than one command can be 
specified in a line. To separate each command, the ampersand (&) character is used. 

Most of the PIP switches operate on lists of file specifications. The exceptions are the /DD, 
/DF, /EX, /ID, and /TD switches, which are used by themselves. 

Table 12-2 lists PIP switches and subswitches and summarizes the functions performed by 
them. The subswitches are listed with their respective switches. The switches and subswitches 
are described in detail in Section 12.1.4. 

Table 12-2: PIP Switches and Subswitches 
Switch Subswitch Function 

/AP Appends file or files to the end of an existing file. 

/FO Specifies the owner of a file. 

/BS Defines the block size for magnetic tape. 

/CD Allows the output file to take the creation date of the input file rather 

than the date of transfer. 

/DD Restricts file searches to files created during a specified period of time, 

/DE Deletes one or more files. 

/LD Lists the deleted files. 

/DF Changes PIP's default device and/or directory. 

/EN Enters a synonym for a file in a directory file. 
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Table 12-2 (Cont.): PIP Switches and Subswitches 



Switch Subswitch Function 



/NV Forces the version number of a file to one greater than the latest version. 

/EOF Specifies the end-of-file (EOF) pointer for a file. 

/EX Excludes one file specification's worth of files during file searches. 

/FT Accesses a file by its file identification number (file ID). 

/FR Displays the amount of available space on the specified volume, the 
largest contiguous free space on ttiat volume, and the number of 
available file headers. 

/ID Identifies the version of PIP being used. 

/LI Lists directory files. 

/BR Lists a directory file in brief format. 

/FU[:n] Lists a directory file in full format. 

/TB Lists the total number of blocks used for a directory, along with the 
total number blocks allocated and the number of files in that directory. 

/ME Concatenates two or more files into one file. 

/BL Allocates a number ( n ) of contiguous blocks. 

/CO Specifies that the output file or files be contiguous. 

/FO Specifies the owner of a file. 

/NV Forces the version number of a file to one greater than the latest version. 

/SU Supersedes (replaces) an existing file. 

/NM Suppresses certain PIP error messages. 

/PR Changes the protection status of a file. 

/FO Specifies the owner of a file. 

/GR Sets the read/write/extend/delete protection at the group level. 

/OW Sets the read/write/extend/delete protection at the owner level. 

/SY Sets the read/write/extend/delete protection at the system level. 

/WO Sets the read/ write/extend/delete protection at the world level. 

/PU Deletes obsolete version or versions of a file. 

/LD Lists the deleted files. 

/RE Renames a file. 

/NV Forces the version number of a file to one greater than the latest version. 
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Table 12-2 (Cont.): PIP Switches and Subswitches 



Switch Subswitch Function 



/RM Removes a file entry from a directory. 

/RW Rewinds a magnetic tape. 

/SB Specifies that records may span disk block boundaries when copied from 

magnetic tape. 

/SD Deletes files selectively by prompting for your response before deleting 

them. 

/SP Spools files to the line printer for printing. 

/SR Allows shared reading of a file that has already been opened for writing 

by another user or task. 

/TD Restricts file searches to files aeated on the current day. 

/TR Truncates files to logical EOF. 

/UF Creates a User File Directory (UFD) entry on the volxmie to which a file 

is being transferred. 

/FO Specifies the owner of a file. 

/UN Unlocks a file. 

/UP Updates (rewrites) an existing file. 

/FO Specifies the owner of a file. 

PIP accepts some switches with no file specification. However, when you use a switch in a 
command line, it must follow the file or directory specification. It cannot come before the device 
name, the directory, the file name, the file type, or the version of the file on which it is to 
operate. 

You may specify a switch once for a list of file specifications as follows: 

f ilespecl ,f ile8pec2,f ilespecS/DE 

The /DE sv>ritch applies to all of the previous file specifications. PIP deletes every specified file 
from its directory. 

You specify switch arguments as octal (default), decimal, or alphabetic characters, depending on 
the switch. Refer to the specific sections that explain the individual PIP switches for information 
on these values. 

You can apply subswitches to one or more file specifications, depending on the placement of 
the subswitch. Subswitches can appear in either the output file specification or the input file 
specification. 

If you place the subswitch in the output file specification, the subswitch applies to the entire 
list of input file specifications. 

If you place the subswitch in the input file specification, it usually applies only to the file 
specification that immediately precedes it. 
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When you explicitly apply a subswitch to a file specification, you implicitly apply the switch with 
which the subswitch is associated. On a command line with more than one file specification, 
the explicit subswitch affects only the file to which it is applied. The implicit switch affects all 
the files on the command line. 

Examples 

PIP>/CO=TEST.TSK; 1, SAMP. DAT ;1 [RET] 

Copies TEST.TSK;1 and SAMP.DAT;! such that the copies, TEST.TSK;2 and SAMP.DAT;2, are 
contiguous. 

Applies the Contiguous Output subswitch (/CO) to both TEST.TSK and SAMP.DAT. (The /CO 
subswitch is used with the Copy function. See Section 12.2.1.) 

PIP>* . SMP=PRT2 . QRT , ASDG . MAC/NV . KG . MAC/RE iHl] 



Applies the New Version subswitch (/NV) to the file ASDG.MAC. (The /NV subswitch is being 
used with the /RE switch.) 

PIP renames the files PRT2.QRT and KG.MAC, but they maintain their associated version 
numbers. File ASDG.MAC is also renamed, but the version number is forced to a number one 
greater than the latest version of file ASDG.SMP (assuming a version of ASDG.SMP already 
exists). 

PIP>FILE1 .CMD/GR:R/W0.FILE2.MAC/GR:RW [M] 

or 

PIP>FILE1 . CMD/GR : R/WO , FILE2 . MAC/GR : RW/PR [RET] 

Provides the following file protection (both command lines are equivalent): 

FILEl SYSTEM Unchanged 

MEMBER Unchanged 

GROUP Read access 

WORLD No access 
FILE2 SYSTEM Unchanged 

MEMBER Unchanged 

GROUP Read/write access 

WORLD Unchanged 
For more information on altering the protection level of a file, see Section 12.1.4.16. 
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12.1.3 Wildcards 

PIP allows you to specify wildcards in file specifications. The wildcard characters are the 
asterisk (*) and the percent sign (%). You can use both wildcards in place of explicit 
specifications for file names and types, and you can use just the asterisk wildcard in place of 
file directories and version numbers. 

The asterisk can denote zero or more characters in the field you specify it in, while the percent 
sign character can denote exactly one character in the fields. Correct syntax must be followed, 
however. See Section 12.1.3.2. 

Wildcards are restricted in some cases. The following sections describe and give examples of 
wildcards in input and output file specifications. 

12.1.3.1 Wildcards in Output File Specifications 

Wildcards in the output file specifications are restricted. For the following PIP functions, the 
output file specification cannot have any wildcards: 

• Concatenating files to a specified file 

• Appending files to an existing file 

• Updating (rewriting) an existing file 

• Listing a directory 

If you use wildcards in the output file specification for any of these functions, the meaning of 
the command line will be ambiguous. 

Note 
The percent sign ( % ) cannot be used in output file specifications. 

Example 

PIP>LIST . *= [200 , 200] /LI [betI 

Shows an incomplete output file specification. PIP returns an error message. 

When you make copies of several files, the output specification must be *.*;* or defaulted from 
the input file specification or specifications. 

For the Rename (/RE) and Enter (/EN) switches, the output specification can have wildcards 
(asterisks oiJy) mixed with specified fields. For either switch, the equivalent field of the input 
file specification is used. 

For all cases in which wildcards are allowed in the output file specification, the wildcard 
directory form [*,*] or [*] is used to indicate that the output directory is to be the same as the 
input directory. 
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12.1.3.2 Wildcards in Input Specifications 

PIP provides the following wildcard features for input file specifications: 

*.*;• Specifies all versions of all files. 

♦.DAT;* Specifies all versions of all files of file type DAT. 

*.D*;* Specifies all versions of all files with file types beginning with D. 

TEST.*;* Specifies all versions of all types of files named TEST. 

T*.*;* Specifies all versions of all types of files with names beginning with T. 

TEST.DAT;* Specifies all versions of file TEST.DAT. 

TEST.D%T;* Specifies all versions of files named TEST with 3-character file types beginning 
with D and ending with T. 

T%N.*;* Specifies all versions of all file types of all 3-character file names beginning 

with T and ending with N. 

*.* Specifies the most recent version of all files. 

*.DAT Specifies the most recent version of all files of file type DAT. 

*%.DAT Specifies the most recent version of all files that have at least one character in 

their names and have the file t5rpe of DAT. 

TEST.* Specifies the most recent version of all file types for files named TEST. 

PIP also provides the following wildcard directory features: 

[*,*] Specifies all group/member number combinations (1 to SZZg). 

[nl,*] Specifies all member numbers under group nl. 

[*,n2] Specifies all group numbers for member n2. 

[*] Specifies all named directories and group/member number combinations. 

Note 

The percent sign ( % ) character cannot be used in the directory. 

12.1.4 PIP Switch Descriptions 

The following sections contain detailed descriptions of the PIP switches used for file control 
functions. Table 12-2 lists these switches and subswdtches for easy reference. 

12.1.4.1 Append 

The Append switch (/AP) opens an existing file and appends the input file or files to the end 
of it. 

Use the Set File Ownership subswitch (/FO) to specify that the owrung UIC of the output file 
is the same directory to which the input file belongs. If you do not specify the /FO subswitch, 
the owning UIC of the output file is unchanged, regardless of the directory to which the input 
files belong. 
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Format 

outme=infile[,...]/AP[/FO] 

Parameters 

outflle 

Specfies the output file specification. Wildcard specifications are not allowed in the output 
file specification. The file type and the record attributes for the output file remain the same 
after the input file or files have been appended to it. The file name and file type for the 
output file must be specified explicitly. 

inflle 

Specfies the input file specification. If the file name, file type, and version are not specified, 
then •.•;• is the default. 

Note 

If the output file is contiguous before the appending, it may not be contiguous afterward. 

Example 

PIP>DU1 : FILEl . DAT ; 1=FILE2 . DAT ; 1 , FILES . DAT ; 1 . FILE4 . DAT ; 1/AP \Mi 

Opens F1LE1.DAT;1 on DUl and appends the contents of F1LE2.DAT;1, FILE3.DAT;1 and 
nLE4.DAT;l to it. 

12.1.4.2 Block Size 

The Block Size switch (/BS) defines the block size for magnetic tapes. This switch allows you 
to read or write bigger blocks onto magnetic tape, thereby saving some of the space taken by 
interrecord gaps. The default block size is 512io bytes per block. 

Format 

outfile/BS:n=infile 

Parameters 

outflle 

Specifies the output file specification. 

n 

Specifies, in octal or decimal, the number of bytes in a block number. 

inflle 

Specifies the input file specification. 

Note 

The /BS switch specifies the block size of the output file. If the block size specified is smaller 
than the actual block size, an I/O error occurs. 
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Example 

PIP>MS:BA.DQC/BS: 2048. =AMBER. DOC IRETI 

Increases the block size of the output file, BA.DOC, to 2048io bytes per block. 

12.1.4.3 Creation Date 

The Creation Date switch (/CD), used in a file transfer command, allows the output file to 
take the date on which the input file was created rather than the date of transfer. You cannot 
use this switch with the explicit or implicit /ME switch and/or with an output magnetic tape 
device. 

Format 

outfile/CD=infile[,...] 

or 

outfile=infile/CD[,...] 

Parameters 

outflle 

Specifies the output file specification. 

inflle 

Specifies the input file specification. 

Example 

Pip>/Li [ret] 

DIRECTORY DBl : [200,200] 
21-N0V-86 14:02 

FILE. DAT; 7 12. 6-DCT-86 16:13 

PIP>TEST.DAT/CD=FILE. DAT/LI fRET] 

DIRECTORY DBl: [200.200] 
21-N0V-86 14:05 

FILE. DAT; 7 12. 6-0CT-86 16:13 

TEST. DAT ;1 12. 6-0CT-86 16:13 

Creates a new file, TEST.DAT, from FILE.DAT and gives it the creation date of FILE.DAT rather 
than the transfer date. 

12.1.4.4 Default Date 

The Default Date switch (/DD) restricts file searches to files created during a specific period of 
time. 

Format 

/DD:startdate:enddate 
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Parameters 

startdate 

Specifies the beginning date of the time period in the form dd-mm-37^. It may be unlimited 
by using the wildcard character ( • ). 

enddate 

Specifies the ending date of the time period in the form dd-mm-yy. It may be unlimited by 
using the wildcard character ( * ). 

Notes 

1. Specif jdng the wildcard for both startdate and enddate negates the /DD switch. For example: 
/DD : * : * 

2. The date restrictions for the file searches are now disabled. 

Examples 

PIP>/DD:01-JUN-86:01-JUL-86&/LI HHI 

Lists all files created from 1 June 1986 to 1 July 1986. 

PIP>/DD:*:l-JUH-86&/LI \M\ 

Lists all files created on or before 1 June 1986. 

PIP>/DD:l-JUN-86:*&/LI [M] 

Lists all files created on or after 1 June 1986. 

12.1.4.5 Delete 

The Delete switch (/DE) deletes files from a directory. Optionally, you can specify that the 
deleted files be listed on your terminal by including the List Deleted Files subswitch (/LD) in 
the command line. 

Format 

infile[,...]/DE[/LD] 

Parameter 

inflle 

Specifies the input file specification. 

Notes 

1. You must specify a version number or a wildcard in its place when using the /DE switch, 

2. Use a version number of ;-l to specify the oldest version of a file. Use a version number 
of ;0 or ; to specify the most recent version. 

3. Wildcards in the file name or file type fields are illegal when a version of ;-l, ;0, or ; is 
specified. 



Peripheral Interchange Program (PIP) 12-11 



4. You must issue the file specification because an unspecified file name, file type, and version 
does not default to *.•;*. 

5. The input file specification can take all the usual forms, including wildcards (even in 
[directory]). The only special requirement is that the version field must always be specified. 

Examples 

PIP>TEST.DAT;-1/DE \M] 

Deletes the oldest version of file TEST.DAT. 

PIP>TEST1.DAT;0.TEST2.DAT;/DE [REH 

Deletes the latest version of files TEST1.DAT and TEST2.DAT. 

PIP>TEST.DAT;5/DE [M] 

Deletes version 5 of file TEST.DAT from the current default directory on the default device. 

PIP>TEST . DAT ; 1 . ; 2/DE [M] 



Deletes versions 1 and 2 of file TEST.DAT from the current default directory on the default 
device. 

PIP>*.OBJ;*.*.TMP;*/DE/LD \M} 

Deletes all versions of all files of the file type OBJ and TMP from the current default directory 
on the default device. It lists all deleted files of both file types. 

PIP>*.OBJ;*/LD,*.TMP;*/DE \M1 

Deletes aU versions of all files of the file type OBJ and TMP from the current default directory 
on the default device. Lists all deleted files of both file types. 

12.1.4.6 Default 

The Default switch (/DF) changes the default device and/or directory for the current PIP task. 

The usual default device of PIP is the user's system device (SYO). 

The usual default directory is the directory under which PIP is currently running. The /DF 
switch alters only the default directory. It does not affect the UIC under which PIP is running, 
nor does it circumvent file protection. 

The /DF switch specified vfith no arguments returns the default device to the user's system 
device (SYO) and the default directory to the UIC from which PIP was invoked. 

Formats 

ddnn:[directory]/DF 

or 

ddnn:/DF 

or 

[directory]/DF 

or 

/DF 
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Parameters 

ddnn 

Specifies the new default device to be applied to subsequent PIP command lines. 

directory 

Specifies the new default directory to be applied to subsequent PIP command lines. 

Examples 

PIP>[27,27]/DF 

Sets the default directory to [27,27]. 

PIP>DU1:/DF [m 

Sets the default device to DUl. 

PIP> DUl : [27 , 27] /DF \M} 

Sets the default device to DUl and the default directory to [27,27]. 

PIP>/DF [RET] 

Returns the user's default device to SYO and the default directory to the UIC from which PIP 
was invoked. 

12.1.4.7 Enter 

The Enter switch (/EN) lets you enter a synonym for a file in a directory or directories on the 
same device. This allows the file to be accessed by more than one name. Also provided is a 
subswitch. New Version (/NV), which forces the version number of the file being entered into 
the directory to a number one greater than the latest version of the file. 

The /NV subswitch may appear on either side of the equal sign. If it appears on the output 
side, all of the files being entered are forced to a version number one greater than the latest 
version of the file. If it appears on the input side, only files that have the /NV subswitch 
appended to them are forced to a number one greater than the latest version. (Specifying the 
/NV subswitch is not necessary when both the input and output files are under the same file 
directory.) 

Format 

outfile=infile[,...]/EN[/NV] 

Parameters 

outflle 

Specifies the file specification for the new directory entry. The output file specification has 
a special property in that the file name, file type, or version may be explicit, wildcard (*), 
or default. A file name, file type, or version field that is either wildcard (*) or default (null) 
means that the corresponding field of the input file is to be used. 
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inflle 

Specifies the input file specification. 

If you specify a device in either the input or output file specification, the device sets the 
default for the other side. If you do not specify a device on either the input or output 
side, the current default device is assumed to be the default device. If both the input side 
and the output side explicitly reference different devices, PIP returns an error message that 
requests that the line be reentered. 

The default input file specification is *.*;*. 
Example 

DIRECTORY DM1 : [200 , 100] 
20-MAR-87 16:00 

RICK.DAT;! 12. l-MAR-87 16:10 

Total of 12. blocks in 1. files 

Shows the contents of the input file directory. 



DIRECTORY DM1 : [101 . 101] 




20-MAR-87 16:10 




JEN.0BJ;2 25. 


18-MAY-87 11:19 


LAU.0BJ;3 18. 


18-MAY-87 12:32 



Total of 43. blocks in 2. files 

Shows the contents of the output file directory. 

PIP> [101 , 101] TWIG/EN= [200 , 200] RICK . DAT ; 1 [RETI 

Produces the follovring output file directory: 

DIRECTORY DM1: [101.101] 
20-MAR-87 16:15 



JEN. OBJ; 2 


25. 


18-MAY-87 11:19 


LAU.0BJ;3 


18. 


18-MAY-87 12:32 


TWIG. DAT ;1 


12. 


20-MAR-87 16:13 



Total of 5B. blocks in 3. files 

12.1.4.8 End-of-File 

The End-of-File switch (/EOF) allows you to specify where the file's end-of-file (EOF) will 
be. This helps in certain situations (for example, system crashes) when a file contains useful 
information but its EOF pointer is wrong; thus, preventing you from obtaining the information. 

EOF is an unprotected file attribute. If you are the file owner or have a system-level UIC, you 
do not need read or write access to read or change this attribute. If you are classified group or 
world to the file owner's UIC, you need read access to read the attribute and write access to 
change it. 

Format 

infile/EOF[:block:byte][,...] 
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Parameters 

inflle 

Specifies the input file specification. 

The file specification must be issued. There is no default. 

block 

Specifies the block number where the EOF pointer is to be placed. Usually, the EOF pointer 
cannot be placed beyond the highest number of blocks allocated to the file. However, if all 
the bytes of the allocated blocks are used, the EOF pointer can be placed in the first byte 
of the next block (/EOF: blocks allocated plus one:0). The block number can be octal or 
decimal. 

byte 

Specifies that the byte location of EOF is the first unused byte of the specified block. The 
byte number can be octal or decimal. The maximum value for b5rte is 7778. 

Notes 

1. If you do not enter either of the values for block and byte, PIP places EOF past the last 
byte of the last block allocated to the file. If you specify a value for either block or byte 
that is greater than the maximum value allowed, PIP returns an error message. 

2. Note that the /EOF switch is local to each file specification and therefore does not default 
from left to right. 

Example 

PIP>A.TMP/EaF:17:253.AA.Thff/E0F [M] 

or 

PIP> A . TMP/EOF : 17 : 253 . AA . TMP/EOF : 23 : [REt] 

Indicates the file AA.TMP has 22 blocks allocated. 

12.1.4.9 File Exclusion 

The File Exclusion switch (/EX) excludes one file specification's worth of files during file searches. 
You can exclude any field in the file specification. The fields can contain characters and/or 
wildcards. Specifying the /EX switch by itself negates it. 

Format 

filespec/EX 

Parameter 

fiiespec 

Specifies the file specification. The file name and/or the file tj^ and/or the version number 
can be a wildcard, but all three fields cannot be wildcards. Also, you cannot specify devices 
or directories. 
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Examples 

PIP>*.CMD;*/EX&/LI [RET] 

DIRECTORY DBl: [301,7] 
8-JUL-87 14:50 
*.CMD;*EXCLUDED 

EXECM.MAC;23 45. 23-FEB-86 14:23 

RUN.TSK;46 5. 29-0CT-86 11:59 

FRANK. OBJ; 16 33. 02-MAY-86 13:58 

DEBBIE. COR; 2 5.0. 14-JAN-87 12:01 

Excludes all files of the type CMD from the search done in *.*;*/LI. 

PIP>/EX \Mi 

Negates the /EX switch. 

12.1.4.10 File Identification 

The File Identification switch (/FI) allows you to access an existing file by its file ID. 

Format 

outfile=/FI:filenum:seqnum 

Parameters 

fllenum 

Specifies the file number. 

seqnum 

Specifies the sequence number of the file. 

Note 

The file ID is assigned by the RSX-llM-PLUS operating system when the file is created. To 
find the file identification number of a file, use the Full List subswitch (/FU). The /FU subswitch 
displays the file identification and sequence numbers and other information describing the file. 

Examples 

PIP>XYZ.TSK=/FI:301:27/EN [Ml 

Uses the /FI switch to create a directory entry for a file. 

PIP>A.B=/FI:30i:27 \M} 

Copies a file by using the /FI switch. 

PIP>/FI:i275:47/LI \M] 

DIRECTORY DR2: FILE ID 001275.000047.0 
8-AUG-87 15:58 

MCR.CMD 1. 29-N0V-86 13:22 

DCL.CMD 1. 29-1I0V-86 13:24 

Lists entries in the directory file whose file identification is 1275,47, using the /FI switch. 
12-16 Peripheral Interchange Program (PIP) 



12.1.4.11 Free 

The Free switch (/FR) displays the amount of available space on a specified volume, the largest 
contiguous space on that volume, the number of available file headers, and the number of file 
headers used. 

Format 

[ddnn:]/FR 

Parameter 

ddnn 

Specifies the device volume. 

Notes 

1. If you do not specify a device, PIP defaults to SYO. 

2. The format of the information from the /FR switch is as follows: 

ddnn: has xxxx. blocks free, yyyy. blocks used out of zzzz. 

Largest contiguous space = nnnn. blocks 

aaaa. file headers are free, bbbb. headers used out of cccc. 

3. Usually, the number of free file headers corresponds to the number of files that can be 
created. However, fragmented files and files that are too large for one file header must be 
allocated more than one file header. 

4. The number of file headers will not exceed the number of files that can be created. 
Example 

PIP>DB7:/FR \M] 

DB7: has 10662. blocks free. 330008. blocks used out of 340670. 

Largest contiguous space = 4189. blocks 

9025. file headers are free, 11931. headers used out of 20956. 

Indicates how much free space there is on the disk DB7. 

12.1.4.12 Identify 

The Identify switch (/ID) identifies which version of PIP is being used. 

When you specify this switch, the version number is listed on the input terminal in the following 
format: 

PIP version Mvvee [(ANSI)] 

Parameters 

w 

Specifies the version number. 

ee 

Specifies the edit number. 
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(ANSI) 

Appears if PIP is linked to an American National Standards Institute File Control Services 
(ANSI PCS). Otiierwise, it is blank. 

Example 

PIP>/ID [Ml 

PIP — PIP version M1340 (ANSI) 

Identifies which version of PIP is being used. 

12.1.4.13 List 

The List switch (/LI) lists one or more files contained in a directory, along with their status 
information. 

The /LI switch lists the following information: 

1. The file name, file type and version in the format: filename.filetype;version 

2. Number of blocks used (decimal) 

3. File code: 

(null) = noncontiguous 
C = contiguous 
L = locked 

4. Creation date and time 

5. Summary line — includes the number of blocks used/allocated and files printed 

Three alternate mode subswitches (/BR, /FU, and /TB) allow you a choice of directory listing 
formats. 

Format 

[listfile=]infile[,. ..]/LI[/subswitch] 

Parameters 

listtiie 

Specifies the file specification to be listed. 

If listfile is not specified, it defaults to TI. 

inflle 

Specifies the input file specification. 

The default for infile is *.*;*. 
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/subswitch 

Specifies the alternate mode subswitch of the /LI switch. The list of possible subswitches 
follows: 

/BR Specifies the brief form of directory listing. This subswitch lists only the file 

name, file type, and version. 

/FU[:n] Specifies the full directory format. 

Because the /FU subswitch format uses protected file attributes, you may need 
read access to get a full directory listing of a file. If you are the file owner or have 
a system-level UlC, you do not need read access. If you are classified group or 
world to the file owner's UIC, you need read access to read the protected attributes 
of the file. (To change the protection level attribute, see Section 12.1.4.16.) 

If specified, n is the number of characters per line. If not specified, the number 
defaults to the buffer size of the output device. 

The /FU subswitch lists the following information: 

1. The file name, file type, and version in the format: file- 
name,filetype;version 

2. The file identification number in the format: file number, file sequence 
number 

3. Number of blocks used/allocated (decimal) 

4. File code: 

(null) = noncontiguous 
C = contiguous 
L = locked 

5. Creation date and time 

6. Owner UIC and file protection in the format: [directory][system,owner, 
group,world]). These protection fields can contain the values R, W, E, or 
D: 

R = Read access permitted 
W = Write access permitted 
E = Extend privilege permitted 
D = Delete privilege permitted 

7. Date and time of the last update plus the number of revisions. 

8. Summary line — contains the number of blocks used, the number of blocks 
allocated, and the number of files 

/TB This subswitch specifies the total number of blocks used for a directory and 

outputs the summary line as follows: 

Total of nnnn./imimun. blocks in xxxx. files 
mum = blocks used 
nmnm = blocks allocated 
xxxx = number of files 
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Examples 

PIP>/TB fRETl 

Produces the following directory listirrg: 

Storage used/ allocated for directory DM1 : [SMITH] 
15-APR-87 15:46 

Total of 145. /150. blocks in 5. files 
PIP>/BR \M] 
Produces the following directory listing: 

DIRECTORY DM1 : [SMITH] 
15-APR-87 15 : 50 

CKTST.MAC;6 
CKTXT.MAC;7 
CKTST.TSK;1 
I0TST.MAC;4 
I0TST.TSK;1 



PIP>/LI [RETl 

Produces the following directory listing: 

DIRECTORY DM1 : [SMITH] 
15-APR-87 16:01 



CKTST.MAC;6 






3. 


15-JAN-87 17:10 


CKTST.MAC;7 






0. 


L 15-JAM-87 18:28 


CKTST . TSK ; 1 






69. 


C 15-JAN-87 17:50 


I0TST.MAC:4 






4. 


20-FEB-87 9:13 


I0TST.TSK;1 






69. 


C 20-FEB-87 10:22 


Total 


of 


145. 


blocks 


in 5. files 



PIP>/FU [RET] 

Produces the following directory listing: 

DIRECTORY DM1 : [SMITH] 
15-APR-87 16:05 

CKTST. MAC; 6 (10.10) 3./3. 15-JAN-87 17:10 

[SMITH] [RVfED , RWED , RWED , R] 
CKTST. MAC;7 (13.14) 0./5. L 15-JAN-87 18:28 

[SMITH] [RWED. RWED. RWED. R] 
CKTST. TSK ;1 (12.13) 69. /69. C 15-JAN-87 17:50 

[SMITH] [RWED, RWED. RWED. R] 
I0TST.MAC:4 (11.11) 4./4. 20-FEB-87 9:13 

[SMITH] [RWED. RWED. RWED. R] 
I0TST.TSK;1 (7.12) 69. /69. L 20-FEB-87 10:22 

[SMITH] [RWED . RWED . RWED . R] 

Total of 145. /150. blocks in 5. files 
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pip>/Li mi] 

Lists the directory of the current default device and directory (equivalent to TI:=*.*;*/LI). 
PIP>LP: = [*.*]/FU:132. \M] 

Lists on the line printer, in full format (132-column listing), all of the directories on the current 
default device. 

PIP>TI:=TEST.DAT/FU [RETI 

Lists on TI the full directory listing for the latest version of TEST.DAT in the current default 
device and directory. 

PIP>JUL13.DIR=[200.200]*.*/LI [RET] 

Lists the latest version of all files in directory [200,200] on the current default device to file 
JUL13.DIR in the default directory on the default device. 

PIP>LP:=[11,*]*.CMD;*/LI \M1 

Lists on the line printer all versions of all files with the file type CMD in all directories in 
group 11. 

PIP>LP.7BR=[11,11]*.CMD;*,*.DAT;*,*.MAC;1 \M] 

Lists on the line printer in brief format all versions of all files with a file type of CMD, all 
versions of all files with a file type of DAT, and all files of file type MAC with a version number 
of 1. These files all reside in the directory [11,11] on the current default device. 

12.1.4.14 Merge 

The Merge switch (/ME) creates a single file from two or more existing files. The /ME switch 
is used in copying Files-11 files and is described in Section 12.2.1. 

12.1.4.15 No Message 

The No Message switch (/NM) suppresses the PIP error messages, "No such files(s)" and "File 
not locked," when you are manipulating files. 

The /NM switch applies not only to the file specification preceding it, but it also applies to all 
file specifications to the right of it. 

Format 

infile[,...][/switch]/NM 

Parameters 

infile 

Specifies the input file specification. 

/switch 

Specifies any combination of appropriate switches and subswitches, for example, the /LI, 
/DE, /PU, or /UN switch and any of its respective subswitches. 
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12.1.4.16 Protect 

The Protect switch (/PR) allows you to set the protection status of a file. File protection is 
provided for the following four categories. 

Category Description 

System Specifies which categories of access the system UICs are allowed to the file (that 

is, UICs with group numbers less than or equal to lOg). 

Owner Specifies which categories of access the owner has allowed. 

Group Specifies which categories of access other members in the same group have. 

World Specifies categories of access given all other UICs. 

For each category, you can specify whether that category can read, write, extend, or delete the 
file. To alter the protection level of a file, you can use either the /PR subswitches (/SY, /OW, 
/GR, or /WO) or octal representation (/PR:n). For either method, if you are the file owner 
or have a system-level UIC, you can alter the protection level without having read or write 
access. However, because the protection level of a file is a protected attribute, you cannot alter 
the protection level if you are group or world to the file owner's UIC. (You can read protected 
attributes if you have read access.) 

The /PR subswitches set the protection level for a file. These subswitches specify which 
protection level is to be altered (others are left intact). The values that follow the switch are 
any of the four letters, R, W, E, and D (for read, write, extend, and delete), in any order. They 
specify which privileges the respective categories can have. If you enter the subswitch and do 
not specify a value, no privileges are granted for that category. 

The subswitches are identified as follows: 



Subswitch Description 



/SY 


System 


/OW 


Owner 


/GR 


Group 


/WO 


World 



Protection can also be specified by an optional octal value on the /PR switch in the following 
format: 



/PR:n 



The variable n is the octal representation of the protection to be assigned to the file. This octal 
number is taken as the new protection word. (See the RSX-UM-PLUS Mini-Reference for the 
list of octal codes.) The format of the protection word is shown in Figure 12-1. 



12-22 Peripheral Interchange Program (PIP) 



Figure 12-1: Format of Protection Word 
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Group 


Owner 


System 
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The Set File Ownership subswitch (/FO) allows you to set the ownership of a file to that of 
the UIC of the directory in which it is entered. (You can change the file ownership at the same 
time you set the protection value.) 

Format 

infile/PR[/SY[:RWED]][/OW[:RWED]][/GR[:RWED]][/WO[:RWED]][/FO] 

Parameter 

Infile 

Specifies the file specification whose protection is being changed. 

The file specification must be issued. There is no default. 
Exampies 

PIP>TEST.DAT;5/PR:3 [RET] 

Denies write and read access to the system for file TEST.DAT;5. 

Bits and 1 are set. Bit set means no access permitted. 

PIP> [200.200] *.*;*/PR/FO \M\ 

Causes all files to be owned by directory [200,200] without changing their protection if there 
are files in directory [200,200] that are owned by another UIC. 

PIP>TEST . DAT ; B/PR/OW : RVlfE/GR : RWE/WO \M} 

Sets the protection level so that the owner and group have RWE privileges (not delete), world 
has no access privileges, and system privileges are unchanged. 



PIP>[*,*]*.*;*/PR:0 [ret] 

Sets the protection level of all files so that all categories are granted all access privileges. 

PIP>DUO :[*,*]*.*; */PR/FO [RET] 

Causes all file owners to be the same UIC as the directory in which the files are entered. 



Peripheral Interchange Program (PIP) 12-23 



12.1.4.17 Purge 

The Purge switch (/PU[:n]) deletes a specified range of obsolete versions of a file. If you specify 
the optional value n and the latest version of the file is m, then all existing versions less than 
or equal to m-n are deleted. Although it is useful to think of this command as deleting all but 
the n most recent versions, it is important to understand that if any versions are already deleted 
between m-n and m, fewer than n versions will be retained. The most recent version of the file 
is always retained. 

If you omit the value n, PIP defaults to 1, and all but the latest version of the file are deleted. 
If n is greater than the number of versions of the specified files, no files are deleted. 

The value n is local and defaults from left to right. This means that if you specify it at the end 
of the command line, it only applies to the infile immediately preceding it. All other infiles 
default to one. However, n applies to all following infiles until you make a new specification 
for n. 

Optionally, you can specify that the names of deleted files be listed on your terminal by using 
the List Deleted files subswitch {/ID). 

Format 

infile[,...]/PU[:n][/LD] 

Parameter 

infile 

Specifies the file specification to be deleted. 

Note that a version number is not needed. If specified, it is ignored. 
Examples 

DIRECTORY DM1 : [200 . 201] 
30-APR-87 10:15 

GARY. MAC ;1 
GARY.MAC;2 
GARY. MAC; 3 
GARY. MAC; 4 
GARY. MAC; 5 
RICK.TSK;4 
RICK.TSK;5 
RICK.TSK;7 

Shows the contents of directory [200,201]. 
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PIP>GARY.MAC/PU:3,RICK.TSK/PU:2 [RET] 
Produces the following directory listing: 

DIRECTORY DM1 : [200.201] 
30-APR-87 10:35 

GARy.MAC:3 
GARY. MAC; 4 
GARY. MAC: 5 
RICK.TSK;7 

The three latest versions (3, 4, and 5) of file GARY.MAC are retained; versions 1 and 2 are 
deleted. 

The two latest versions of fae RICK.TSK are not deleted. Because file RICK.TSK;6 does not 
exist, only RICK.TSK; 7 remains in the directory. 

PIP>*.0BJ.*.MAC/PU:2/LD [RET] 

Deletes all but the highest version of all files with a file type of OBJ, and all but the two highest 
versions of all files with a file tjrpe of MAC. All deleted files are listed. 

PIP>*.0BJ/PU:2/LD,*.MAC [RET] 

Deletes all but the two highest versions of all files with file types of OBJ and MAC. Lists all 
deleted files. 

12.1.4.18 Rename 

The Rename switch (/RE) changes the name of a file. There is also a New Version subswitch 
(/NV) that forces the renamed file to have a version number one greater than the latest version 
of the previously existing file with the same name. 

The /NV subswitch may appear on either side of the equal sign. If it appears on the output 
side, all of the version numbers of files being renamed are forced to a number one greater than 
the latest version for the file. If it appears on the input side, only the file that has the subswitch 
appended to it has its version number forced to one greater than the latest version of the file. 
(Specifying the /NV subswitch is not necessary when both the input and output files are under 
the same directory file.) Note that you cannot rename a file that is copied from one device to 
another device. 

Caution 

Directories may still be accessed under the old directory name if the directory 
is in the Ancillary Control Processor's (ACP's) least-recently-used (LRU) list 
because the file ID is used to lookup directories. Renaming a directory pushes 
the directory out of the LRU list, thus ensuring that the directory can only be 
accessed by using the new name. 

Format 

outfile=infile[,...]/RE[/NV] 
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Parameters 

outfile 

Specifies the file specification to be given to the new file. The output file specification has a 
special property in that the file name, file type, and version are each allowed to be explicit, 
wildcard ( * ), or default (null). A directory, file name, file type, or version field that is either 
wildcard (♦) or default (null), means that the corresponding field of the input file is to be 
used. Thus, the /RE switch can change one or more fields while preserving the others. 

inflle 

Specifies the file specification to be renamed. The input file specifications are standard and 
allow wildcards in all fields, including directory. 

An unspecified file name, file type, and version defaults to *.*;*. 

The /RE switch does not transfer data. The file is entered in the new directory and deleted 
from the old directory. The directories must be on the same device because data is not 
transferred. You can move files out of one directory into another, preserving the file name, 
file type, and version, or changing them if desired. (This is permitted only if PIP is running 
under a UIC with write privileges for each of the directories involved.) 

If you specify a device on either the input or output side, that device sets the default for the 
other side. If both the input side and the output side explicitiy reference different devices, 
PIP returns an error message and requests that you reenter the line. 

Examples 

PIP>TESTFILE . DAT ; 1=TEST . DAT : 5/RE [RET] 

Renames TEST.DAT;5 to TESTFILE.DAT;!. 

PIP>BACKUP.*:*=TEST.*;*/RE [RET] 

Renames all versions of all files with file names TEST to BACKUP, preserving the file type and 
version of each file. 

PIP>*.*;1=*.*;*/RE HH] 

Renames all copies of all files to version 1 . 

PIP> [200. 220] = [200. 200] /RE [RET] 

Renames all files from directory [200,200] to directory [200,220], preserving the file name, file 
type, and version of each file. 

PIP>EXAMPLE.*;*=TEST.*;*/RE fRFfl 

Renames all versions of all files with the file name TEST to the file name EXAMPLE, preserving 
the file type and version of each file. 

DIRECTORY DR02: [JONES] 
22-MAR-87 10:30 

SAVE. DAT; 2 
SAVE. DAT; 3 
SAVE. DAT; 4 
OUTPUT.DAT; 1 
OUTPUT. DAT; 2 

Shows the contents of directory [JONES]. 
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PIP>SAVE.DAT/RE=OUTPUr.DAT;l [RET] 

Produces the folowing directory listing: 

DIRECTORY DR02: [JONES] 
22-MAR-87 10:35 

SAVE. DAT; 2 
SAVE.DAT;3 
SAVE. DAT; 4 
SAVE. DAT ;1 
OUTPUT. DAT; 2 

PIP> SAVE . DAT/RE/NV=OUTPUT . DAT ; 1 [RETI 

Produces the folowing directory listing: 

DIRECTORY DR02 : [JONES] 
22-MAR-87 10:30 

SAVE. DAT; 2 
SAVE. DAT; 3 
SAVE. DAT; 4 
SAVE. DAT; 5 
OUTPUT. DAT;2 

12.1.4.19 Remove 

The Remove switch (/RM) removes an entry from a directory, but it does not delete the file 
associated with that entry. The /RM sv«tch is particularly useful for deleting directory entries 
that, for whatever reason, point to nonexistent files. It is also used to delete synonyms generated 
by the /EN switch. If the last entry for an existing file is removed, that file can be located only 
by using the VFY utility with its /LO switch (see Chapter 14). 

Caution 

Directories may still be accessed after using the /RM switch if the directory is in 
the ACP's LRU list because the file ID is used to lookup directories. Renaming 
a file pushes the directory out of the LRU list, thus ensuring that the directory 
cannot be accessed by using the file name that was removed. 

Format 

infile[,...]/RM 

Parameter 

inflle 

Specifies the file specification for the directory file entry to be removed. 

The file specification must be issued. There is no default. 
Example 

PIP>DU1 : [10 . 10] RICKSFILE . DAT ; 1/RM [RET] 

Removes the file enby RICKSFILE.DAT; 1 from the directory [10,10] on DUl. 
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12.1.4.20 Rewind 

The Rewind switch (/RW) directs PIP to rewind magnetic tape. (The /RW switch cannot be 
used for DECtapes.) You can apply this switch to both input and output specifications. When 
you specify the /RW switch with the output specification, PIP begins writing the file at the 
ijegjnning of the tape. You can use this technique to erase a tape before writing files on it. 

When you apply the /RW switch to the input specification, it rewinds the tape before searching 
for the input file. The magnetic tape processor performs the following process when it searches 
for a file to open: 

1. Searches from the current position to end of tape 

2. Rewinds the tape 

3. Searches from the beginning of tape to the point where search processing began 

You can use the /RW switch with the input specification to save search time. If you know a 
file is behind the tape's current position. The /RW switch rewinds the tape before searching for 
the file to open. This saves the time that othervdse would have been taken to search for the 
file between the current position and the end of the tape. 

Formats 

outfile/RW=infile 

or 

outfile=infile/RW 

Parameters 

outfiie 

Specifies the output file specification. 

inllle 

Specifies the input file specification. 

Examples 

PIP>MS:/RW=[200.200] IRETI 

Starts the beginning of the tape and outputs all files in directory [200,200]. 

PIP> AMBER. DOC=MS:AB.D0C/RW \M] 

Rewinds the tape, searches the tape for the file AB.DOC, renames the file AMBER.DOC, and 
outputs the file. 
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12.1.4.21 Span Blocks 

The Span Blocks switch (/SB) allows you to control whether records copied from magnetic tape 
to disk will cross block boundaries. If you omit this switch, the file is copied with records 
possibly crossing block boundaries. If you specify the /-SB switch, the records will not cross 
block boundaries. 

Format 

ddnn:outfile/SB=mmnn:infile 

Parameters 

ddnn 

Specifies the output disk volume. 

outfile 

Specifies the disk output file specification. 

mmnn 

Specifies the input tape volume. 

inflle 

Specifies the magnetic tape input file specification. 

Example 

PIP>DU1 : FILES . DAT/-SB=MMO : FILES . DAT [REtI 

Copies FILES.DAT records to the disk from magnetic tape. Records on the disk will not cross 
block boundaries. 

1 2. 1 .4.22 Selective Delete 

The Selective Delete switch (/SD) prompts for your response before deleting a file that you 
have specified in the command line for deletion. The response choices are pressing the RETURN 
key, CTRL/Z, Y, N, G, or Q; each followed by pressing either the RETURN key or CTRL/Z. 
Table 12-3 describes the effect of each combination of letter and terminator. 

Format 

infile[,...]/SD 

Parameter 

inflle 

Specifies the input file specification. 

The file specification must be issued. There is no default. 
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Y 


fRETl 


Y 


ICTRL/Zl 


[N] 


|ret| 


[N] 


ICTRL/Zl 


Q 


fREf] 


Q 


ICTRL/Zl 


G 


|ret| 


G 


ICTRL/Zl 



Table 12-3: Response Choices for the Selective Delete Switch 

Letter Terminator Operation 

Deletes file and continues. 

Deletes file and exits from PIP. 

Saves file and continues. 

Saves file and exits from PIP. 

Saves file and returns to command mode. 

Saves file and exits from PIP. 

Deletes current file and all remaining candidates, lists deleted files, and 
returns to PIP command mode. 

Deletes current file and all remaining candidates, lists deleted files, and 
exits from PIP. 

Examples 

PIP>MYFILE.DAT;*/SD [REtI 

DELETE FILE DBl: [200, 200] MYFILE.DAT ; 1 [Y/N/G/Q]? Y [RET] 
DELETE FILE DBl: [200. 200] MYFILE.DAT; 2 [Y/N/G/Q]? G [M] 

THE FOLLOWING FILES HAVE BEEN DELETED: 
DBl : [200 , 200] MYFILE . DAT ; 2 
DBl : [200 , 200] MYFILE . DAT ; 3 
PIP> 

Deletes MYFILE.DAT;! and then PIP goes to the next candidate, MYFILE.DAT;2. It deletes this 
file and all remaining versions of MYFILE.DAT. It lists the deleted files and then PIP prompts 
for the next command. 

PIP>TEST.*;*/SD [RET] 

DELETE FILE DBl: [200. 200] TEST, DAT; 1 [Y/N/G/Q]? N [RET] 
DELETE FILE DBl: [200. 200] TEST. TXT; 3 [Y/N/G/Q]? Q ICTRL/Zl 

Saves TEST.DAT;1 and then PIP goes on to the next candidate, TEST.TXT;3. It saves this file 
and all remaining files with file name TEST and then exits from PIP. 

12.1.4.23 Spool 

The Spool switch (/SP) directs a file to a line printer for printing. This switch applies only if 
you have the Queue Manager installed. (For more information on the Queue Manager, see the 
RSX-llM-PLUS Batch and Queue Operations Manual.) 

Format 

infile[,...]/SP[:n] 



12-30 Peripheral Interchange Program (PIP) 



Parameters 

inflle 

Specifies the file specification to be spooled for printing. 

The file specification must be issued. There is no default. 

If the file is specified by its file ID, it will be printed. File IDs are discussed in 
Section 12.1.4.10. 

n 

Specifies the number of copies you want spooled. (If a deleting spooler was specified during 
system generation, only one copy of a file is printed, regardless of the value of n. The file 
is deleted after the first copy has been printed.) If n is omitted, a value of 1 is assumed. 

Example 

PIP>RICK1.LST:1.KATHY.LST;1./FI:12:22/SP \Mi 

Spools the files RICKl.LST;!, KATHY.LST;1, and the file whose file ID is 12:22 for asynchronous 
printing. 

12.1.4.24 Shared Reading 

The Shared Reading switch (/SR) allows you to read a file that has already been opened for 
writing by another task. You have no guarantee that you will get the information you want 
since the EOF pointer may be incorrect at the time you open the file. 

Format 

outfile=infile/SR 

Parameters 

outflle 

Specifies the output file specification. 

inflle 

Specifies the input file specification. 

Example 

PIP>TI: = [210.20]FILES.DAT/SR [Ml 

Enables you to read FILES.DAT even though another task may have already opened it for 
writing. 
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12.1.4.25 Today Default 

The Today Default switch (/TD) restricts file searches to files created on the current day. 

Format 

/TD 

Note 

Specifying the wildcard for both start date and end date of the /DD switch (/DD:*:*) also 
negates the /TD switch. 

Example 

PIP>/TD&/LI fRET] 



DIRECTORY DB2: [301,357] 
20-JAN-87 11:02 
DAY OF 20-JAN-87 



TEST. DAT ;1 


1. 


20-JAN-87 10:40 


FILES.TXT; 1 


1. 


20-JAN-87 10:41 


INFO. DAT ;1 


1. 


20-JAN-87 10:50 



TOTAL OF 3./15. BLOCKS IN 3. FILES 
Lists the files created on the current date. 

12.1.4.26 Truncate 

The Truncate switch (/TR) allows you to truncate files back to their logical end-of-file (EOF) 
point. Note that RMS- 11 files other than those that are fixed length, variable length, or 
sequenced cannot be truncated. 

File Control Services (FCS) allocates a certain number of blocks to a file. The file may or may 
not use the number of blocks allocated to it. The /TR switch frees the unused blocks for use 
by other files. 

Format 

infile[,...]/TR 

Porameter 

inflle 

Specifies the input file specification. 

The file specification must be issued. There is no default. 
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Examples 

PIP>*. MAC/LI [RET] 

DIRECTORY DR2: [301.7] 
2-AUG-87 15:32 

A.MAC:! 3. 20-SEP-86 14:02 

B.MAC; 1 2. 20-SEP-86 15:38 

C.MAC: 2 5. 28-SEP-86 09:54 

TOTAL OF 10. /15. BLOCKS IN 3. FILES 

Lists the files with type MAC. 

PIP>*.MAC/TR \M} 
PIP>*. MAC/LI [RET] 



DIRECTORY DR2: [301,7] 
2-AUG-87 15:33 

A.MAC:1 3. 20-SEP-86 14:02 

B.MAC;1 2. 20-SEP-86 15:38 

C.MAC: 2 5. 28-SEP-86 09:54 

TOTAL OF 10. /lO. BLOCKS IN 3. FILES 

Truncates, and then lists, the files with type MAC. 

12.1.4.27 User File Directory 

The User File Directory switch (/UF) creates a directory entry in the Master File Directory (MFD) 
on the volume to which you are transferring a file. You must also transfer ownership of the 
file to access the file. Use the /FO subswitch to transfer file ownership, and use [*,*] as the 
directory in the output file specification if you want to create the directory or directories from 
which you are obtaining the files being transferred. 

To use the /UF switch, you must have write access to the Master File Directory (MFD) of the 
volume on which the files are being written. If that volume is a system volume, you must have 
a system-level UIC to use the /UF switch. If the volume to which you are writing files is your 
private volume, use the following procedure to change your UIC so you can write to it: 

1. Log in to the system under your UIC. 

2. Reset your UIC to a privileged class by using the SET command: SET /UIC=[group,member]. 
Group and member specify a privileged class. 

A tj^ical use of the /UF switch is creation of a backup volume. 

Format 

outfile/UF[/FO]=infile[,...] 

Parameters 

outflle 

Specifies the file specification for the output file. 

inflle 

Specifies the file specification for the input file. 
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Example 

PIP>DU6 :[*,*] /UF/FO=SY : [104 , 20] * . MAC , * . OBJ [RETI 

Writes all files with file types OBJ and MAC in directory [104,20] to a backup volume called 
DU6. 

12.1.4.28 Unlock 

The Unlock switch (/UN) unlocks (gives permission to open) a file that was locked because 
it was improperly closed. If a program using FCS has a file open with vrate access and exits 
without first closing the file, the file is locked against further access as a warning that it may 
not contain proper information. Typically, the foUovnng information is not written to the file: 

• Current block buffer being altered 

• Record attributes that contain the EOF information 

After you have used the /UN switch, you can access the file, determine the extent of the 
damage, and, if possible, take corrective action. 

You must run PIP under the UlC of the file owner or under a system-level UIC. 

Format 

infile[,..]/UN 

Parameter 

inflle 

Specifies the file specification for the file to be unlocked. 

The file specification must be given. There is no default. 
Example 

PIP>DU1 : [100 , 100] RICKl . OBJ ; 3/UN fRET] 

Unlocks the file R1CK1.0BJ;3 in directory [100,100] on device DUl. 

12.1.4.29 Update 

The Update switch (/UP) is similar to the basic PIP copy function or the /ME switch except 
that an existing file is opened and new data is written into it from the beginning. Existing data 
in the output file is destroyed and replaced by the data that constitutes the input file or files. 
Unlike the Supersede subswitch (/SU), the /UP switch does not delete the existing file before 
rewriting the data. Therefore, its file ID remains the same. Also, the number of blocks allocated 
to the output file can be the same or greater, but they can never be less than the number of 
blocks allocated to the existing file. However, as with the /SU subswitch, the file name, type, 
and version number remain the same. 

Use the Set File Ownership subswitch (/FO) to transfer file ownership. The /FO subswitch 
specifies that the owning UIC of the output file corresponds to the directory into which the file 
was entered. If you do not specify the /FO subswitch, the owning UIC of all new files is the 
UIC under which PIP is running, regardless of the UIC into which the file was entered. 
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Format 

outfile=infile[,...]/UP[/FO] 

Parameters 

outflie 

Spedfies the file specification for the file to be rewritten. 

The output file specification must be explicit; that is, no wildcards are allowed. 

The characteristics and record attributes of the output fQe are taken from the first input file. 

inflle 

Specifies the file specification for the file to be copied into the file that is being rewritten. 

An unspecified file name, file type, and version default to *.*;*. 
Example 

PIP>PU1 : SAMPLE . DAT ; 1=TEST1 . DAT ; 1 . TEST2 . DAT ; 1 . TESTS . DAT ; 1/UP [RETI 

Opens SAMPLE.DAT;! on DUl and replaces the data currently in the file with the contents of 
files TESTl.DAT;!, TEST2.DAT;1, and TEST3.DAT;1. 

12.2 PIP Command Functions 

PIP copies Files-11 files and performs file control functions. The copying function and file 
control functions are described in the following sections. 

12.2.1 Copying and iVIerging Files-11 Files 

To copy Files-1 1 files, you can enter the PIP command line without specif)dng any switches. 
The simplest format for the PIP command line is shown here. 

Format 

outfile=infile 

Parameters 

outfile 

Specifies the output file specification. If the output file name, file type, and version are either 
defaulted or "*.*;*," the input file name, file type, and version are used for the output file 
(see the /NV and /SU subswitches). If you explicitly specify any portion of the output file 
specification (file name, file type, or version), wildcards cannot be used in this specification. 
Similarly, for a copy command, if you enter any portion of the output specification, you 
can enter only one file as the input file. 

infile 

Specifies the input file specification. If the file name, file type, and version fields are not 
specified, then "•.*;•" is the default. 
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One switch that you can specify when copying Files-11 files is the Merge switch (/ME). The 
/ME switch creates a new file from two or more existing files. PIP assumes the /ME switch 
when you explicitly specify an output file, two or more input files, and no switches. Because 
the basic copy function and the /ME switch are logically related, the /ME switch is described 
here rather than with the other switches. 

The general format of the PIP command line is shown here. 

Format 

outfile=infile[,...][[/ME][/subswitch]] 

Parameters 

outflle 

Specifies the output file specification. 

inflle 

Specifies the input file specification. 

/ME 

Specifies the Merge switch. 

subswitch 

Specifies any of the subswitches that you can enter as part of the basic command line or 
with the /ME switch. Subswitches can appear in either the output or input file specifica- 
tion. If you place the subswitch in an input file specification, it applies only to that file. If you 
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place the subswitch in the output fUe specification, it applies to the entire list of input 
specifications. The subswitches are as follows: 

/BL:n The Blocks Allocated subswitch specifies the number of blocks (n) to allocate 

initially to the output file. You can specify n as either an octal or decimal 
value (decimal values must be followed by a decimal point). You can use the 
/BL subswitch when you are copying a contiguous file and changing its size. 

/CO The Contiguous Output subswitch specifies that the output file be contiguous. 

When you are copying contiguous files from magnetic tape (for example, task 
images), specify both the /CO and /BL subswitches. You must specify the 
/BL subswitch because PIP cannot determine the length of the input file when 
copying from tape. (PIP allocates file space before the copy operation is 
executed. The length of magnetic tape input files is on the trailing label for 
the file.) 

/-CO The Noncontiguous Output subswitch specifies that the output file does not 

have to be contiguous. 

If you do not specify the /BL subswitch, the /CO subswitch, or the /-CO 
subswritch, PIP defaults to the size and attributes of the input file. 

/FO The Set File Ownership subswitch specifies that the owner of the output file 

v«ll be the same as the output directory. If you do not specify the /FO 
subswitch, the UIC of all new files is the UIC under which PIP is running, 
regardless of which directory the files belong to. You can use this subswitch 
with both copy and merge commands. 

When you specify the /FO subswitch, PIP must be running under a UIC that 
has write access to all output directories. 

/NV The New Version subswitch forces the output version number of the file being 

copied to become one greater than the latest version of the file already in 
the output directory. If the file does not already exist in the output directory, 
a version number of 1 is assigned. (Specifying the /NV subswitch is not 
necessary when both the input and output files are under the same file 
directory.) 

/SU The Supersede subswitch allows you to copy one or more input files to a file 

whose file name, file type, and version may already exist in a directory. The 
existing file is deleted and a new one is created with the data from the input 
file or files. If the file does not already exist, it is created. 

The output file's name, type, and version number remain the same, but its 
file identification number (file ID) may be different. Also, the attributes for 
the output file are taken from the first input file and the number of blocks 
allocated to the output file can be different (less than or more than) from the 
number of blocks allocated to the existing file. 

Examples 

PIP>DU1: SAMP. DAT=DU2: TEST. DAT [RfT] 

Copies the latest version of file TEST.DAT (in the current directory) from DU2 to DUl, and 
names it SAMP.DAT. 
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PIP>DU1:[*,*]=DU0:[11,*] [RETl 

Copies all files from all members in group iiumber 11 of DUO to DUl. The files are copied 
to the same directory or\ DUl that they were in on DUO. Note that the user must have write 
access to all group number 11 directories on DUl. 

PIP>LP:=*.LST IMl 

Copies the latest version of all files with a type of LST in the current directory to the line 
printer. This command line is used if the Print Spooler is not installed on your system. 

When you specify LP as your output device, the data to be printed is vmtten into an intermediate 
file and then the file is given to the Queue Manager, which handles the spooling. Making 
intermediate files allows you to dismount the volume the files are on without having to wait 
until after they have been printed. 

PIP>*.LST/SP [Ml 

Copies the latest version of all files with a type of LST in the current directory to the line 
printer. The Spool switch (/SP) is used if the Print Spooler is installed on your system. 



PIP>DU1 : SAMP . DAT=DU2 : TEST . DAT ; 1 , NEW . DAT ; 2/ME [RET] 

Concatenates version 1 of file TEST.DAT and version 2 of file NEW.DAT from DU2, and 
generates file SAMP.DAT on DUl using the current directory. Note the result would be the 
same if the /ME switch was not specified. 

PIP>DU1 : =DB2 : TESTPROG . MAC , . OBJ [M] 

Copies the latest versions of TESTPROG.MAC and TESTPROG.OBJ from DB2 to DUl, using 
the current directory for both DB2 and DUl. 



PIP>DK1:=DK0:*.DAT:* [RETl 

Copies all versions of all of the files of file type DAT in the current directory from DUO to DUl. 

PIP>DT0: = [200.10]*.*;* [RET] 

Copies all files under directory [200,10] from the default device (SY) to DTO, using the current 
directory. 

PIP> DPO : [200 . 10] =DTO : * . * [RET] 

Copies the latest versions of all files from DTO in the current directory to DP0:[200,10]. Note 
that the user must have write access to directory [200,10]. 

PIP> DUO : [200 , 200] =DU1 : [200 , 220] TEST . DAT [M] 

Creates a new file in the directory [200,200] on DUO, but the file is owned by User Identification 
Code (UIC) [1,1], which is the UIC under which PIP is running. 

PIP>DU0 : [200 . 200] =DU1 : [200 . 220] TEST . DAT/FO [RET] 

Creates a file owned by UIC [200,200], even though PIP is running under UIC [1,1]. 

PIP>DU1 :[*,*] /F0=DPO : [13 . 10] . [32 . 10] , [34 , 10] \Mi 

Copies all the files from the specified input directories to the corresponding directories on DUl. 
The file owners are the output directories. 
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PIP>DU1 :[*.*] =DUO : [* , 10] * . MAC/FO [RETI 

Copies all the MAC files from all group numbers with member 10 to DUl, preserving the 
directory and setting the file owner for each file to that directory. 

DIRECTORY DKl : [201,201] 
20-MAR-87 11:05 

RICK. DAT ;1 12. l-MAR-87 16:10 

Total ol 12. blocks in 1. files 

Shows the contents of the input directory. 



DIRECTORY DKl : [100 . 100] 




20-MAR-87 11:10 




RICK.DAT;2 14. 


3-MAR-87 17:05 


RICK. DAT; 3 20. 


lO-MAR-87 10:22 



Total of 34. blocks in 2. files 
Shows the contents of the output directory. 
PIP>DK1: [100, 100] =DK2: [201, 201] RICK. DAT ;1 HH] 
Results in the following output directory: 



DIRECTORY DKl : [100. 100! 


1 






20-MAR-87 11 : 15 








RICK. DAT; 2 


14. 


3-MAR-87 


10:22 


RICK. DAT; 4 


20. 


lO-MAR-87 


10:22 


RICK. DAT ;1 


12. 


20-MAR-87 


11:12 



Total of 46. blocks in 3. files 



PIP>DK1: [100,100]=DK2: [201.201]RICK.DAT;1/NV [RET] 
Results in the following output directory: 



DIRECTORY DK1:[10( 


),100] 


1 




20-MAR-87 11:20 








RICK. DAT; 2 




14. 


3-MAR-87 10:22 


RICK. DAT; 4 




20. 


lO-MAR-87 10:22 


RICK. DAT; 5 




12. 


20-MAR-87 11:17 



Total of 46. blocks in 3. files) 

12.2.2 Performing File Control Functions 

PIP pro\ddes several switches and subswitches for file control processing. These switches and 
subswitches perform such functions as deleting files, displaying the contents of a directory, and 
specifying file protection values. 

You can specify several PIP switches in a command line with no file specifications (that is, they 
may be entered by themselves). These switches include /DD, /DF, /ID, and /TD switches. 

You can specify one or more commands in a line. When you use multiple commands, the 
ampersand ( & ) character separates each command. 



Peripheral Interchange Program (PIP) 12-39 



Example 

PIP>TEST . DAT ; 2=SAMP . DAT ; 2/SU , SAMP . DAT ; IfcTEST . DAT ; */FUfcSAMP . DAT/PU/LD [Ml 
Performs the following steps: 

1. PIP merges SAMP.DAT;2 and SAMP.DAT;! into TEST.DAT;2. The /SU subswitch causes 
TEST.DAT's file name, file type, and version number to remain the same, but TEST.DAT;2's 
contents are replaced with the input file's contents. 

2. The /FU subswitch causes PIP to do a full format listing of all versions of the file TEST.DAT. 

3. The /PU switch causes PIP to purge SAMP.DAT, and the /LD subswitch causes PIP to list 
the deleted files. 

The values that you specify with the switches and subswitches default to octal. You can specify 
decimal values by adding a decimal point after the value. 

12.3 PIP Error Messages 

Errors encountered by PIP during processing are displayed in the following format: 

PIP — <main error me88age> 

<filename or f llespec> - <8econdar7 error ne8sage> 

The file name or file specification, if present, identifies the file or set of files being processed 
when the error occurred. If the error was detected by the operating system, file system, or 
device driver, the secondary error message is included to explain the cause of the error. 

PIP error messages are contained in a message file on the system device. If PIP cannot access 
the message file, errors are reported in the following format: 

PIP — ERROR CODE nn. 

<filename or filespec> - <driver Code -mm.> 

or 

<QIO Error Code -qq.> 

Parameters 

nn 

Specifies one of the PIP error codes (see Section 12.3.1) 

mm 

Specifies one of the standard system, file primitive, or FCS codes listed in the RSX-UM-PLUS 
and Micro/RSX I/O Operations Reference Manual 

qq 

Specifies one of the directive error codes listed in the RSX-llM-PLUS and Micro/RSX I/O 
Operations Reference Manual 
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Error messages describe a condition that caused PIP to terminate the processing of a command. 
When this occurs, PIP returns to the highest level of command input. For example, if the 
command is entered in response to the Monitor Console Routine (MCR) prompt, PIP will issue 
the error message, exit, and prompt you with the MCR prompt, as follows: 



>PIP coiimEindllne 
PIP — message 
> 

If the command is entered in response to the PIP prompt, PIP will issue an error message and 
prompt you with the PIP prompt, as follows: 

PIP>coiiuiiandline 
PIP — message 
PIP> 

The PIP error messages, their descriptions, and suggested user actions are as follows: 

PIP — Allocation foilure - no contiguous space 

Explanation: Not enough contiguous space was available on the output volume for the file 
being copied. 

User Action: Delete all files that are no longer required on the output volume and then 
reenter the command line. Also, use the Backup and Restore Utility (BRU) or the Disk 
Save and Compress Utility (DSC) to compress the files on your disk. BRU is described in 
Chapter 3 and DSC is described in Chapter 6. 

PIP — Allocation failure on output die 
or 

PIP — Allocation failure - no space available 

Explanation: Not enough space was available on the output volume for the file being copied. 

User Action: Delete all files that are no longer required on the output volume; then, reenter 
the command line. Also, use the BRU or DSC utilities to compress the files on your disk. 
BRU is described in Chapter 3 and DSC is described in Chapter 6. 

PIP — Bad use of wildcards/characters in destination file name 

Explanation: A wildcard/character was specified for an output file name when use of a 
wildcard/character was explicitly disallowed. 

User Action: Reenter the command line with the output file explicitly specified. 

PIP — Cannot exclude •.•;• 

Explanation: The /EX switch does not accept all wildcards as the input file specification. 
User Action: Determine the files to be excluded and reenter the command line. 
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PIP — Cannot find directory file 

Explanation: The specified directory does not exist on the volume. 

User Action: Specify the con-ect directory or the correct volume and reenter the command 
line. 

PIP — Cannot find flle(s) 

Explanation: The file or files specified in the command line were not found in the designated 
directory. 

User Action: Check the file specification and reenter the command line. 

PIP — Cannot renanne from one device to anottier 

Explanation: You attempted to rename a file across devices. 

User Action: Rename the file on the input volume and reenter the command line; then, 
enter another command to transfer the file to the intended volume. 

PIP — Cannot truncate ttils flletype 

Explanation: PIP can only truncate files containing fixed-length, variable-length, and 
sequenced records. 

User Action: Check the file specification and reenter the command line. 

PIP — Close failure on input file 
or 

PIP — Close failure on output file 

Explanation: The input or output file could not be properly closed. If the failure is on the 
output file, the output file is then locked to indicate possible corruption. 

User Action: Reenter the command line. If the error recurs, run a validity check of the file 
structure by using the File Structure Verification Utility (VFY) on the volume in question to 
determine if it is corrupted. VFY is described in Chapter 14. 

PIP — Command syntax error 

Explanation: Command did not conform to syntax rules. 

User Action: Reenter the command line with the correct syntax. 

PIP — Device not mounted or ottier privilege violation 

Explanation: The drive had not been allocated, the device was not mounted, or another user 
had mounted the device. 

User Action: Allocate the drive and/or mount the device; then, reenter the command line. 
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PIP — Directory write protected 

Explanation: PIP could not remove an entry from a directory because the device was wrrite- 
protected or because of a privilege violation. 

User Action: Enable the device for write operations or have the owner of the directory 
change its protection. 

PIP — Error from parse 

Explanation: The specified directory file does not exist. 

User Action: Reenter the command line vdth the correct User Identification Code (UIC) 
specified. 

PIP — Explicit output file name required 

Explanation: You did not specify an output filename. 

User Action: Reenter the command line vwth the output filename explicitly specified. 

PIP — Failed to attocti output device 
or 

PIP — Failed to detach output device 

Explanation: An attempt to attach/detach a record-oriented output device failed. This is 
usually caused by the device being off line or nonresident. 

User Action: Ensure that the device is on line and reenter the command line. 

PIP — Failed to attach terminal 

Explanation: PIP could not attach a terminal, probably because of a privilege violation. 
User Action: Determine the cause of the failure and correct it. Reenter the command line. 

PIP — Failed to create output UFD 

Explanation: PIP could not create an entry in a directory because the device was write- 
protected or because of a privilege violation. 

User Action: Enable the unit for write operations or have the owner of the directory change 
its protection. 

PIP— Failed to delete file 
or 

PIP — Failed to mark tile for delete 

Explanation: You attempted to delete a protected file. 

User Action: Request PIP under the correct UIC and reenter the command line. 
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PIP — Failed to enter new file name 

Explanation: You specified a file that already exists in the directory file, or you did not have 
the necessary privileges to make entries in the specified directory file. 

User Action: Reenter the command line, ensuring that the file name and directory are 
specified correctly, or request PIP under the correct UIC and reenter the command line. 

PIP— Failed to find flle(s) 

Explanation: The file or files specified in the command line were not found in the designated 
directory. 

User Action: Check the file specification and reenter the command line. 

PIP — Failed to get time parameters 

Explanation: An internal system failure occurred while PIP was trying to obtain the current 
date and time. 

User Action: Reenter the command line. If the problem persists, submit a Software 
Performance Report (SPR). 

PIP — Failed to open Index file 

Explanation: PIP was unable to read the index file, probably because of a privilege violation. 

User Action: Retry the operation by running PIP under a system UIC, or have the system 
manager change the protection on the index file. 

PIP — Failed to open storage bitmap file 

Explanation: PIP could not read the specified volume's storage bit map, probably because 
of a privilege violation. 

User Action: Retry the operation by running PIP under a system UIC, or have the system 
manager change the protection on the storage bit map. 

PIP — Failed to read attributes 

Explanation: The volume you specified was corrupted or you did not have the necessary 
privileges to access the file. 

User Action: Ensure that PIP is running under the correct UIC. If the UIC is correct, then 
run the validity check of VFY against the volume in question to determine where and to 
what extent the volume is corrupted. VFY is described in Chapter 14. 

PIP — Failed to remove directory entry 

Explanation: PIP could not remove an entry from a directory because the unit was write- 
protected or because of a privilege violation. 

User Action: Enable the unit for write operations or have the owmer of the directory change 
its protection. 
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PIP — Failed to restore original directory entry - file is lost 

Explanation: PIP removed a file from a directory, failed to enter it (using the /RE switch) 
into another directory, and failed to replace the original directory entry. 

User Action: Run VFY and use the /LO switch to recover the file name. VFV is described 
in Chapter 14. 

PIP — Failed to spool die for printing 

Explanation: The Queue Manager is not installed, or the file was being spooled by file ID. 

User Action: Install the Queue Manager or specify the file name, and reenter the command 
line. 

PIP — Failed to truncate fiie 

Explanation: The volume you specified is corrupted or you did not have the necessary 
privileges (write, extend) to truncate this file. 

User Action: Ensure that PIP is running under the correct UIC. If the UIC is correct, then 
run the validity check of the VFY against the volume in question to determine where and 
to what extent the volume is corrupted. VFY is described in Chapter 14. 

PiP — Failed to write attributes 

Explanation: The volume you specified is corrupted or you did not have the necessary 
privileges to write the file attributes. 

User Action: Ensure that PIP is running under the correct UIC. If the UIC is correct, then 
run the validity check of the VFY against the volume in question to determine where and 
to what extent the volume is corrupted. VFY is described in Chapter 14. 

PIP — File block has Forced Error Bit set 

Explanation: A bad block replacement was needed during a read operation. The replacement 
block has a "forced error" bit set and may contain corrupt data that was read out of the bad 
block. The message occurs when the replacement block is being merged or appended to 
other files. The transfer of the file with the replacement block is then aborted. The records 
contained in the replacement block and all subsequent blocks vwll not be transferred. PIP 
will continue with the next element in the list, if one exists. 

User Action: If the file is needed, copy the file with the replacement block to an output file 
and use the File Dump Utility (DMP) to examine the contents of the file or, if the problem 
is known, use the Task/File Patch Utility (ZAP) to correct the problem. 

PIP— File is lost 

Explanation: PIP removed a file from its directory, failed to delete it, and failed to restore 
the directory entry. 

User Action: Run VFY and use the /LO switch to recover the file name. The VFY utility is 
described in Chapter 14. 
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PIP — File not locked 

Explanation: The /UN switch was entered for a file that was not locked. 
User Action: Specify the correct file and reenter the command line. 

PIP — Get Command Line - bad @ (lie name 

Explanation: An illegal indirect command file name was specified. 

User Action: Specify the correct name for the indirect command file and reenter the command 
line. 

PIP — Get Command Line - failed to open @ file 

Explanation: PIP could not find the specified indirect command file. 

User Action: Check the specification for the indirect command file and reenter the command 
line. 

PIP — Get Command Line - I/O error 

Explanation: An 1/0 error occurred during an attempt to read a command line. 

User Action: Check the command to ensure that you entered it correctly; then, reenter the 
command line. If the error persists, submit an SPR. 

PIP — Get Command Line - max @ file depth exceeded 

Explanation: The maximum level of nesting for indirect command files ( 4 ) was exceeded. 
User Action: Reduce the level of nesting. 

PIP — Illegal command 

Explanation: The command was not recognized by PIP. 

User Action: Reenter the command line with the PIP command correctly specified. 

PIP — illegal EOF value 

Explanation: You specified an illegal block and/or byte value in the command line. 
User Action: Reenter the command line with the correct values. 

PIP — Illegal response - try again 
Explanation: Self-explanatory. 
User Action: Check your response and enter it when PIP prompts you. 

PIP — liiegal switch 

Explanation: The specified switch was not a legal PIP switch. 

User Action: Reenter the command line with the correct switch specification. 
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PIP — Illegal "•" copy to same device and directory 

Explanation: You attempted to copy all versions of a file into the same directory that is 
being scanned for input files. This would result in an infinite number of versions of the 
same file, which is not allowed. 

User Action: Rename the files or copy them into a different directory; then, reenter the 
command line. 

PIP — Illegal use of wildcard version or latest version 

Explanation: The use of either a wildcard version number or a latest version number in the 
attempted operation would result in inconsistent or unpredictable output. 

User Action: Reenter the command line with different options or with an explicit or default 
version number. 

PIP — Input files hiave conflicting attributes 

Explanation: The input files specified with a Merge, Update, or Supersede switch had 
conflicting attributes, or the attributes of the input file or files specified with an Append 
switch conflicted with those of the output file. 

User Action: The message is a warning only. The specified action was completed despite 
the conflict. With a Merge, Update, or Supersede switch, the attributes of the output file 
will be those of the first input file. With an Append switch, the attributes of the output file 
are unchanged. The resulting file should, however, be suspect because its attributes may 
not correctly represent all the records in the file. 

PIP — I/O error on input file 
or 

PIP — I/O error on output file 

Explanation: One of the following conditions may exist: 

• The device is not on line. 

• The device is not mounted. 

• The hardware has failed. 

• The volume is full (output only). 

• The input file is corrupted. 

Note that these are the most common conditions. Conditions other than those listed may 
have caused the message. 

User Action: Determine which condition caused the message and correct that condition; 
then, reenter the command line. 
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PIP — Not a directory device 

Explanation: A directory-oriented command was issued to a device that does not have 
directories (such as a printer). 

User Action: Reenter the command line without specifying DIRECTORY. 

PiP — Not enough buffer space availobie 

Explanation: PIP did not have enough I/O buffer space to perform the requested command. 

User Action: Have the system manager install PIP in a larger partition, or increase the 
size specified by using the /INC switch with the MCR command INSTALL (see the 
RSX-llM-PlUS MCR Operations Manual) or by using the /EXTENSION qualifier with the 
DCL command INSTALL (see the RSX-llM-PLUS Command Language Manual). 

PiP— No such flle(s) 

Explanation: The file or files specified in the command were not found in the designated 
directory. 

User Action: Check the file specification and reenter the command line. 

PIP — Only [•,•] is legal as destination UIC 

Explanation: A UIC other than [*,*] was specified as the output file UIC for a copy operation. 
User Action: Reenter the command line with [*,*] specified as the output UIC. 

PIP — Open failure on Input llle 
or 

PIP — Open failure on output tile 

Explanation: The specified file could not be opened. One of the following conditions may 
exist: 

The file is protected against access. 

A problem exists on the physical device (for example, device cycled down). 

The volume is not mounted. 

The specified file directory does not exist. 

The named file does not exist in the specified directory. 

Note that these are the most common conditions. Conditions other than those listed may 
have caused the message. 

User Action: Determine which condition caused the message and correct that condition; 
then, reenter the command line. 
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PIP — Output file already exists — Not superseded 

Explanation: An output file of the same name, type, and version as the file specified already 
exists. 

User Action: Retry the copy with the /NV subswitch to assign a new version number or 
use the /SU subswitch to supersede the output file. 

PIP — Too many command switches - ambiguous 

Explanation: Too many switches were specified or the switches conflict. 

User Action: Specify the correct set of switches and reenter the command line. 

PIP — Version must be explicit or "•" 

Explanation: The version number of the specified file must be expressed explicitly or as a 
wildcard (•). 

User Action: Reenter the command line with the version number correctly expressed. 
PIP — WARNING — File may contain corrupt data 

Explanation: A bad block replacement was needed during a read operation. The replacement 
block may contain corrupt data that was read out of the bad block. This message occurs 
only when the input file is being copied to its own output file. 

User Action: Delete the file if desired. If the file is needed, use the File Dump Utility (DMP) 
to examine the contents of the file or, if the problem is known, you can use the TASK/FILE 
Patch Utility (ZAP) to correct the problem. 

12.3.1 PIP Error Codes 

Table 12-4 identifies the error codes PIP issues when it does not have access to the message 
file. The descriptions and suggested user actions for these error codes are identical to those 
described in Section 12.3. 

Table 12-4: PIP Error Codes 

Error Code Error Message 

1 Command syntax error 

2 Illegal switch 

3 Too many command switches - ambiguous 

4 Only [♦,*] is legal as destination UIC 

5 Illegal command 

6 Illegal ■"•" copy to same device and directory 

7 Bad use of wildcards/characters in destination file name 

8 Explicit output file name required 
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Table 12-4 (Cont.): PIP Error Codes 

Error Code Error Message 

9 Allocation failure - no contiguous space 

10 Allocation failure - no space available 

11 Allocation failure on output file 

12 I/O enor on input file 

13 I/O error on output file 

14 Illegal use of wildcard version or latest version 

15 Failed to create output directory 

16 Input files have conflicting attributes 

17 Open failure on input file 

18 Open failure on output file 

19 Close failure on input file 

20 Close failure on output file 

21 Failed to detach output device 

22 Device not mounted/allocated 

23 Output file already exists - not superseded 

24 Failed to mark file for delete 

25 File is lost 

26 Version must be explicit or "*" 

27 Error from parse 

28 Failed to delete file 

29 Failed to attach terminal 

30 Illegal response - try again 

31 Cannot exclude *.*;* 

32 Cannot find directory file 

33 Failed to attach output device 

34 Failed to get time parameters 

35 Not a directory device 

36 Failed to write attributes 

37 Failed to read attributes 
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Table 12-4 (Cont.): PIP Error Codes 

Error Code Error Message 

38 File not locked 

39 Failed to enter new file name 

40 Failed to restore original directory entry - file is lost 

41 Cannot rename from one device to another 

42 Failed to spool file for printing 

43 Cannot spool by file ID (RSX-llD only) 

44 Failed to open storage bitmap file 

45 Failed to open index file 

46 Failed to find file(s) 

47 Cannot find file(s) 

48 No such file(s) 

49 Failed to remove directory entry 

50 Directory write-protected 

51 Not enough buffer space available 

52 Failed to truncate file 

53 Cannot truncate this filetype 

54 Illegal EOF value 
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Chapter 13 



Source Language Input Program (SLP) 

The Source Language Input Program (SLP) is a utility used to maintain and audit source files. 
The optional audit trail in the output files allows you to keep a record of maintenance changes. 

SLP is invoked by edit command statements and switches. SLP edit command statements allow 
you to perform the following tasks: 

• Update (delete, replace, and add) lines in an existing file 

• Create source files 

• Run indirect command files containing SLP edit commands 

Input to SLP is a file that you want updated and command input consisting of text lines and 
edit command lines that specify the update operations to be performed. To locate lines to be 
changed, SLP uses line numbers or character strings that you specify. Command input can 
come directly from your terminal or from an indirect command file containing commands and 
text lines to be inserted into the file. SLP accepts data from any Files-11 volume. 

Output from SLP is a listing file and the updated input file. SLP provides an optional audit 
trail that helps you keep track of the update status of each line in the file. If an audit trail is 
not suppressed, it is shown in the listing file and is permanently applied to the output file. 

You can control SLP processing with SLP control switches. These switches allow you to perform 
the following tasks: 

Suppress audit trails 

Specify the length and beginning position of the audit trails 

Calculate the checksum value for the edit commands 

Generate a double-spaced listing 

Spool files to a Files-11 volume 
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13.1 SLP Input and Output Files 

SLP requires two types of input: an input file and command input. The input file is the source 
file you want to update by using SLP. Command input consists of SLP edit commands and, 
optionally, new lines of text to be placed in the file. 

SLP output consists of an output file and a listing file. The output file is the updated input file. 
The listing file is a copy of the output file with line numbers added. Both show the changes 
SLP made to the file. 

13.1.1 Input File 

The input file is the file to be updated by SLP. It can contain as many lines of text as are 
required. When SLP processes the input file, it makes the changes specified by SLP edit 
commands. If an audit trail is generated, these changes are noted in the output files. 

13.1.2 Command Input 

SLP uses command input to update files. Command input can be entered interactively after 
you invoke the SLP utility or indirectly by means of indirect command files. 

You enter command input to SLP in two modes: command mode and edit mode. After it is 
invoked, SLP is in command mode, where the first line entered must be the command line 
defining the files to be processed. When SLP accepts this line, it initializes the files you want 
processed. Once these files are initialized, SLP enters edit mode, where it interprets the lines 
you enter as SLP edit commands or new input lines. 

You terminate command input with a single slash ( / ) as the first character of an edit command 

line. 

An example of the general form of command input is as follows: 

MYFILE . MAC ; 2/CS/AU: 55 : 10 . MYFILE . LST ; 1/-SP=MYFILE . MAC ; 1 

-3../;BJ007/ 

CMP (R1)+.B 

-4,4 

DEC R2 

/ 

Note 

Numeric values given for switches defaxilt to octal. Decimal values must be 
followed by a period ( . ). The default position for the audit trail is 80io and 
its default length is 8io; no more than 14io characters may be specified. (See 
Section 13.5.2 for more information about the audit trail.) 

The first line is the command line, where you define the output file, the listing file, and the 
input file. The next four lines comprise the SLP edit commands and input lines. 

Note that the input and output files in the command line have the same file name and file 
type; only the versions are different. To ensure that the correct files are processed, specify the 
version numbers explicitly when you enter the SLP command line. Wildcards cannot be used 
in any of the file specifications. 

You can also calculate the checksum value for the edit commands by specifying the checksum 
switch (/CS) with either the input or output file specification. 



13-2 Source Language Input Program (SIP) 



The checksum value can be calculated for all SLP edit command lines. The checksum value 
cannot be calculated for the following: 

• The command line specifying the input and output files 

• Comments in the edit command lines 

• Any spaces and/or tabs between characters included in the checksum calculation and those 
characters excluded from the calculation 

• The second comma (,) and anything following it in an edit command line (that is, audit 
trail and/or coiiunent) 

• Comment delimiter (specified by the first character of the last audit trail string before the 
current delimiter) and any characters following it in an input line, whether or not it is being 
used in the line as a delimiter 

The value n is then reported in a message on your terminal. If you specify a value n for the 
checksum and it is not the same as the calculated checksum, you will get a diagnostic error 
message. (These messages are described in Section 13.6.3.) 

13.1.3 SLP Listing File 

The SLP listing file shows the updates made to the source file. Each line in the listing file is 
numbered. Updates are marked by means of the audit trail if one has been generated. The 
examples given throughout this chapter contain samples of listing files. 

13.1.4 SLP Output File 

The SLP output file is the updated input file. All of the updates specified by command input 
are inserted in this file. The audit trail, if specified, is applied to lines changed by the update. 
The audit trail is included in the output file. The numbers generated by SLP for the listing file 
do not appear in the output file. 

13.2 How SLP Processes Files 

Figure 13-1 shows how SLP processes files when it receives the follovdng command line and 
edit commands: 

MYFILE . MAC ; 2/AU : 55 : 10 , MYFILE . LST/-SP=MYFILE . ^aC ; 1 

-3 

CMP (R1)+,B 

-4.4 

DEC (R2) 

/ 
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Figure 13-1: Input Files and Output Files Used During SLP Processing 

Input File 



Listing File 



MYFILE.MAC;1 



MYFILE.LST;! 



Command Input 



From Primary From Indirect File 

Input Device or INFILE.SLP;1 




t> 



SLP 
Processor 



Output File 



MYFILE.MAC;2 



C> 



The following file is the input file (MYFILE.MAC;1) before the previous SLP commands were 
processed: 



MOV #BUF1,R0 


MOV #SIZ.R1 


CALL READ 


TST R2 




BEQ END 




CLR Rl 




MOV R2.NUMC 


CMPB (RO: 


»+.A 


BNE 20$ 




INC Rl 




following file is the listing file (MYFIL 


1. MOV 


#BUF1 ,R0 


2. MOV 


#SIZ.R1 


3. CALL 


READ 


4. CMP 


(R1)+,B ;**NEW** 


5. DEC 


(R2) ;**NEW** 


6. BEQ 


END ;**-l 


7. CLR 


Rl 


8. MOV 


R2.NUMC 


9. CMPB 


(RO)+,A 


10. BNE 


20$ 


11 . INC 


Rl 
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The audit trail shows the new lines (;**NEW**) and indicates where lines have been removed 
(;**-l). (The audit trails ;**NEW** and ;**-n are automatically generated by SLP if you have 
not suppressed audit trail generation or if you have not specified another audit trail string.) In 
this case, a line has been added eifter line 3, and line 4 has been deleted and a new line added 
in its place. 

As shown in Figure 13-1, SLP processes an input file by using command input. When processing 
begins, SLP writes each line from the input file into the output file until it reaches a line to 
be modified, as requested in the command input. When SLP reaches a line to be modified, it 
modifies the line, notes the change by means of the audit trail, and then continues writing lines 
to the output file until another command is encountered or until end-of-file (EOF) is reached. 

13.3 SLP Edit Command Lines 

The SLP edit commands allow you to update source files by adding, deleting, and replacing 
lines in a file. SLP allows you to enter lines sequentially. Once past a given line in the file, 
you cannot return the line pointer to that line. To return the line pointer to that line, you must 
begin another SLP editing session. 

You can invoke SLP by all but one of the methods for invoking a utility described in Chapter 1. 
You cannot include a command line on the same line on which you invoke SLP. That is, you 
cannot type the following command line: 

>SLP fllespec 

Also, you should not specify TI as your output file because, when you finish editing, you will 
not have a copy of the output file and the input file will be the same as before you began 
editing. 

All fields in the SLP edit command line are positional and commas (,) must be specified. 

The SLP edit command line is shown next. 

Format 

-[locatorl][,locator2][,/audittrail/][; comment] 
inputline 



Parameters 

- (dash) 

Identifies an SLP edit command line. 

locator! 

Specifies a line locator field that causes SLP to move the current line pointer to a spec- 
ified line. If you specify only locator 1, the current line pointer is moved to that line and SLP 
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reads the next line in the command input file. This field can be specified by using any of 
the locator formats, as follows; 

-/string/ [+n] 
-/string. . . string/ [+n] 
-number [+n] 
-.[+n] 

The parameters for the locator formats are as follows: 

string Specifies a string of American Standard Code for Information Interchange 

(ASCII) characters. SLP locates the line where the string exists and moves 
the current line pointer to that line. If the locator is specified in the form 
/string... string/, SLP locates the line where the two character strings delimit 
a larger character string abbreviated by an ellipsis (...). 

number Specifies a decimal line number where the current line pointer is to be moved. 

The largest line number that can be specified is 9999. 

(period) Specifies the current line. 

n Specifies a decimal value used as an offset from the line specified by the 

locator. You cannot use +n by itself. It must be specified with a number or 
string locator or a period. SLP moves the current line pointer n lines beyond 
the line specified in the locator field. 

Although the values for number and n are taken as decimal, remember that all other SLP 
values are octal by default. 

All forms of the line locator can be specified interchangeably in the SLP edit command 
lines. 

locator2 

Specifies a line locator field that defines a range of lines (that is, the range beginning with 
locatorl and ending with locator2) to be deleted or replaced. This field can be specified by 
using any of the locator formats described previously. 

audittrail 

Specifies a character string used to keep track of the update status of each line in the file. 
The string must be enclosed within slashes (/). It consists of a comment delimiter as 
the first character and then a text string. The semicolon (;) is the default delimiter for 
audit trails automatically generated by SLP (;**NEW** and ;**-n). The comment delimiter 
specified in audittrail (usually a semicolon) is the new delimiter for all subsequent audit 
trails until redefined by a later audit trail. 

comment 

Specifies a line of text (delimited by a semicolon) at the end of the SLP edit command line 
that appears only in the command input file. 

inputline 

Specifies a line of new text to be inserted into the file immediately following the current 
line. You can enter as many input lines as required. 
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Once you have invoked SLP, you can enter SLP edit commands interactively or by specifying 
indirect command files. In both cases, the first command you must enter is the command line 
defining the files to be processed during this SLP session. 

The following file (BASE.MAC;1) is used as the input file for the example in Section 13.3.1: 



MOV 


#$SWTCH.R3 


CLE 


$ERFLG 


CLR 


SCRCVL 


CLR 


$CSSV 


MOV 


SPSAV.SP 


MOV 


#$CFNMB,RO 


MOV 


#<$HDSIZ-$CFNMB>/2+l ,R1 


CLR 


(R0) + 


DEC 


Rl 


BNE 


5$ 



13.3.1 Entering SLP Commands Interactively 

To alter the example file interactively, first invoke SLP by using any method described in 
Chapter 1 (except > SLP filespec). 

SLP responds to this command with the following prompt: 

SLP> 

Once you have entered the SLP command mode, SLP does not display prompts. The first line 
you enter must always be the command line defining the files you want processed during this 
session. Then you enter the edit commands and input lines. 

When you have entered all the corrections, enter the slash ( / ) to terminate the editing session. 
SLP processes the files and returns control to you with the following prompt; 

SLP> 

This returns SLP to command mode. You can then enter another input file and begin another 
editing session. 

Example 

SLP>BASE . MAC ; 2/AU : 48 . /TR . BASE . LST=BASE . MAC ; 1 [Ml 

-3 [m 

TST Rl IMl 

-4.4 \M] 

BEQ 10$ Mi 

-6.,/:JM010/ [M] 

CLR R2 [Ml 

/ 

SLP> 

Instructs SLP to do the following: 

-3 Inserts a new line after line 3. 

-4,4 Deletes line 4 and replaces it with a new line. 

-6„/;JM010/ Inserts a line after line 6 v«th a new audit trail value. 
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The following file is the listing file (BASE.LST;!) produced by the previous SLP command lines: 



1. 


MOV 


#$SWTCH.R3 




2. 


CLR 


$ERFLG 




3. 


CLR 


SCRCVL 




4. 


TST 


Rl 


; **NEW** 


5. 


BEQ 


10$ 


; **NEW** 


6. 


MOV 


SPSAV.SP 


;**-! 


7. 


MOV 


*$CFNMB,RO 




8.? CLR 


R2 


iJMOlO 


9. 


MOV 


#<$HDSIZ-$CFNMB>/2+l ,R1 




10. 


CLR 


(R0) + 




11. 


DEC 


Rl 




12. 


BNE 


5$ 





The /TR switch in the previous command line records the truncation of lines by the audit trail. 
In the listing file, a question mark (?) replaces the period ( .) after the line number for the lines 
that were truncated. It is possible that audit-trail strings in the input file will be truncated by 
the new audit-trail string, although the commands or text strings will not be truncated. 

13.3.2 Entering SLP Commands by Using indirect Command Files 

To alter the example file by using the SLP edit commands in the indirect command file, 
BASE.SLP, you invoke SLP and it responds with the following prompt: 

SLP> 

You then enter the file specification for the indirect command file containing the command line, 
the SLP edit commands, and the input lines as follows: 



ABASE. SLP [RETJ 

SLP processes the files just as if you entered the commands and input lines interactively, 
returning control to you with the following prompt: 

SLP> 

You can also specify the following command line: 

SLP OBASE.SLP [RET] 

The output listing resulting from indirect command file processing is exactly like the output 
listing resulting from the same changes made interactively. 

Indirect conimand files can be nested to a maximum level of three. This permits indirect 
command files to reference a text file. 
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13.3.3 Entering and Using SLP Operators 

In addition, you can enter spedal characters called operators, which perform specific functions. 
Table 13-1 lists the operators and the function each performs. You enter operators, in edit 
mode, as the first character of an input line. 

Toble 13-1: SLP Operators 

Operator Function 

Identifies the first character of a SLP edit command line. 

\ Suppresses audit-trail processing. 

% Reenables audit-trail processing. 

@ Invokes an indirect command file for SLP processing. 

/ Terminates the SLP edit session, and then returns to SLP command mode. 

< Enables you to enter characters in the input file that SLP otherwise would interpret 

as operators. For example, </ hides the slash character from SLP, thereby 
enabling you to enter the slash into the output file without terminating the SLP 
editing session. This character can be used with all SLP operators. 

13.4 Updating Source Files witli SLP 

This section describes the procedure for generating a numbered listing for use in editing source 
files by line number. The section also describes how to use SLP to add, delete, and replace 
lines in a file. 

13.4.1 Generating a Numbered Listing 

SLP processes input by line number. However, line numbers appear only in the listing file; 
they are not written to the output file. To use SLP effectively, you should use a numbered 
listing when you prepare command input. To generate a numbered listing, first invoke SLP, 
and then enter the command line in the format shown next. 

Format 

,listfile=infile 
/ 

Parameters 

listflle 

Specifies the name you assign to the listing file SLP produces. 

Inflle 

Specifies the name of the input file whose lines are to be numbered. 

/ 

Terminates edit mode. 
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Example 



MOV 


Rl.-(SP) 


BIC 


#177770. eSP 


ADD 


#60,eSP 


MOVB 


(SP)+.-(RO) 


ASR 


Rl 


ASR 


Rl 


ASR 


Rl 


DEC 


R2 


BNE 


30$ 


MOV 


#MS6,R0 



Processes each line in the previous input file and generates the following numbered list file 
(listfile;!): 



1. 


MOV 


R1,-(SP) 


2. 


BIC 


#177770, «SP 


3. 


ADD 


#60.«SP 


4. 


MOVB 


(SP)+,-(RO) 


5. 


ASR 


Rl 


6. 


ASR 


Rl 


7. 


ASR 


Rl 


8. 


DEC 


R2 


9. 


BNE 


30$ 


10. 


MOV 


#MSG.RO 



13.4.2 Adding Lines to a File 

There are three SLP edit command formats for adding lines to a file, as follows: 

Format 

-locatorl 
inputline 



or 

-locatorl,, 
inputline 



or 

locatorl„/audittrail/ 
inputline 
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Examples 

SLP>MYFILE . MAC ; 2/AU : 48 . : 10 . /TR . MYFILE . LST/-SP=MYFILE . MAC ; 1 

-3 \M] 

CMP (R1) + .B [RET] 

-4.4 [Ml 

DEC R2 \Mi 

-6..,/;JM010/ \m] 

INC R3 [RET] 

-9,,/;BJ008/ [M] 

BEQ 10$ (Ml 

/ 

Shows how to add lines to a file. 

SLP>MYFILE . MAC ; 2/ AU : 50 , MYFILE . LST=MYFILE . MAC ; 1 [M] 

-/BEQ/ \m] 

CALL WRITE [RET] 
/ 

Indicates where new lines should be added or deleted by using text rather than line numbers. 

The edit command /BEQ/ instructs SLP to insert a line after the line with the first occurrence 
of BEQ. 

SLP processing generates the following listing file (MYFILE.LST;!): 



1. 


MOV 


#BUF1.R0 


2. 


MOV 


#SIZ,R1 


3. 


CALL 


READ 


4. 


TST 


R2 


5. 


BEQ 


END 


6. 


CALL 


WRITE 


7. 


CLR 


Rl 


8. 


MOV 


R2.NUMC 


9. 


CMPB 


(RO) + .A 


10. 


BNE 


20$ 


11. 


INC 


Rl 



• **NEW** 



SLP has numbered the lines and applied an audit trail to the line following line 5, where SLP 
found the first occurrence of the string BEQ. 



SLP>MYFILE . MAC ; 2/AU : 50 . MYFILE . LST=MYFILE . MAC ; 1 (RET] 

-/#SIZ/+2 [ret] 

CMP (R1) + .B [Hlj 

/ 

Uses the same input file as the previous example to generate the following listing file (MYFILE;!): 



; **NEW** 



1. 


MOV 


#BUF1.R0 


2. 


MOV 


«SIZ.R1 


3. 


CAU 


READ 


4. 


TST 


R2 


5. 


CMP 


(R1) + ,B 


6. 


BEQ 


END 


7. 


CLR 


Rl 


8. 


MOV 


R2.NUMC 


9. 


CMPB 


(RO)+,A 


10. 


BNE 


20$ 


11. 


INC 


Rl 
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Again, SLP has numbered the lines and this time the new input line is inserted so that it is two 
lines beyond the line containing the first occurrence of the string /#SIZ/. 

13.4.3 Deleting Lines from a File 

The SLP edit command format for deleting lines from a file is shown next. 

Format 

-[locatorl],[locator2],[/audittrail/][; comment] 

Parameters 

locator] 

Specifies, in any of the forms of the locator fields described in Section 13.3, the line where 
SLP is to begin deleting lines. 

locator2 

Specifies, in any of the forms of the locator fields described in Section 13.3, the last line to 
be deleted. 

SLP deletes all lines from locatorl to locator2, inclusive. 



MOV 


#BUF1.R0 


MOV 


#SIZ,R1 


CALL 


READ 


TST 


R2 


BEQ 


END 


CLE 


Rl 


MOV 


R2,NUMC 


CMPB 


(RO) + .A 


BNE 


20$ 


INC 


Rl 



Shows the contents of the input file. 

SLP>MYFILE . MAC ; 2/AU : 50 , MYFILE . LST=MYFILE . MAC ; 1 [RET] 

-/MOV. ..Rl/,/NUMC/ \M} 

I 

Deletes lines from the input fQe and generates the following listing file (MYFILE;!): 

1. MOV #BUF1.R0 

2. CMPB (RO)+,A 

3. BNE 20$ 

4. INC Rl ;**-6 

In the previous command lines, the ellipsis (...) abbreviates the larger string MOV #SIZ,R1. 
Assuming the two strings bracket a larger string, SLP searches for the first occurrence of the 
string MOV and then the first occurrence on the same line of the string Rl, in this case the 
string MOV #SIZ,R1. SLP begins deleting lines at this line and continues deleting lines until 
it deletes the last line of the given range, which is specified here by the string NUMC. SLP 
applies the audit-trail count of the lines it deleted to the next line from the input file. 
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SLP>MYFILE . MAC ; 2/AU : 50 . MYFILE . LST=MYFILE . MAC ; 1 [REtI 

-/MOV #SIZ,R1/,. [m 

/ 

Uses the same input file from the previous example to delete a sirigle line by using the period 

locator, and it generates the following listing file (MYFILE;!): 



1. 


MOV 


#BUF1.R0 


2. 


CALL 


READ ;**-! 


3. 


TST 


R2 


4. 


BEQ 


END 


5. 


CLR 


Rl 


6. 


MOV 


R2.NUMC 


7. 


CMPB 


(RO)+.A 


8. 


BNE 


20$ 


9. 


INC 


Rl 



SLP moves the current line pointer to the line containing the string MOV #SIZ,R1 and then 
finds the period as the second locator field. Since the second locator field is specified as the 
current line, SLP deletes the current line. 

13.4.4 Replacing Lines in a Fiie 

A replacement is the deletion of old text followed by the insertion of new text. The number of 
lines deleted need not match the number of lines added. To replace lines in a file, use the same 
SLP edit command format as used in the delete command. The first line locator field specifies 
the first line to be deleted. The second line locator field defines the last line in the range to be 
deleted and where the new text is to be inserted. 

Examples 

-4 , . +4 

Instructs SLP to move the line pointer to line 4, and replaces line 4 and the next four lines with 
new input lines. 



MOV 


#BUF1,R0 


MOV 


#SIZ.R1 


CALL 


READ 


TST 


R2 


BEQ 


END 


CLR 


Rl 


MOV 


R2,NUMC 



Shows the contents of the input file. 
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SLP>MYFILE . MAC ; 2/AU : 50 . MYFILE . LST=MYFILE . MAC ; 1 [M] 

-2,.+l \M] 

CMP (R1) + ,B [M] 

INC R2 fRgfl 

/ 

Deletes lines from the previous input file and replaces them with new lines. The edit command, 
-2,.+l, instructs SLP to delete lines 2 and 3 and insert two new lines. SLP processing then 
generates the following listing file (LISTING;!): 

;**NEW** 
; **NEW** 

;**-2 



1. 


MOV 


#BUF1,R0 


2. 


CMP 


(R1)+,B 


3. 


INC 


R2 


4. 


TST 


R2 


5. 


BEQ 


END 


6. 


CLR 


Rl 


7. 


MOV 


R2,NUMC 



13.5 Creating Source Files Using SLP 

Using SLP to create source files is possible, but it is not recommended. SLP does not have an 
intraline editing mode and you cannot return to a line once you have passed it. An interactive 
editor, such as EDI or EDT, is better for creating source files. 

To create source files using SLP, invoke SLP and enter the con\mand line. 

Format 

outfile/-AU[/switch][,listfile][/switch]=[primary_input_device:[/switch]] 

Parameters 

outfiie 

Specifies the file specification for the output file. 

The format for entering file specifications is as follows: 

ddun : [directory] filename . type ; version 

Refer to Chapter 1 for detailed descriptions of the parameters for file specifications. 

The default device is SYO. 

-AU 

Specifies that an audit trail is not to be generated. Otherwise, you will get the ;**NEW** 
audit trail on every line of the output files. 

switch 

Specifies any optional SLP switches. 

listfile 

Specifies the file specification for the listing file (optional). The default device is implied by 
the output file specification. 
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primary_input_device: 

Specifies that input for the fUe being created is coming from this device, for example, a 
terminal. The default device is your primary input device. 

Example 

SLP>MYFILE . MAC/-AU=TI : FreH 

Creates the file MYFILE.MAC on SYO from your terminal without generating an audit trail. 

Once you have entered the file specification, SLP accepts each line as a variable-length record 
of up to 132io characters. Trailing blanks and tabs on input lines are deleted. SLP expects input 
to the file to come from the primary input device. End the SLP session with a slash ( / ) and 
press CTRL/Z. 

13.5.1 SLP Switches 

The SLP switches allow you to calculate the checksum value for the edit commands and to 
control the generation and format of the listing file and the output file. 

SLP output consists of two files: a listing file and the output file, which is the modified version 
of the input file. You can use the SLP switches to control the audit trail and print options 
associated with the two files. 

The effects of SLP switches are the same whether you apply them to input or output files 
(except for the /SP switch, which you can specify only with the listing file). Table 13-2 lists 
the SLP switches and gives a brief description of the functions each performs. 

Table 13-2: SLP Switches 



Switch Format 



Function 



[/AU:position:length] 
/-AU 



[/BF] 
/-BF 



/CM[:n] 



/CS[:n] 



/DB 
[/-DB] 



Allows you to generate an audit trail or suppress the /-AU switch audit- 
trail generation and specify the beginning field (position) and length of 
the audit trail. The /AU switch is the default. See the following sections 
for more information about the /AU switch. 

Positions the audit trail by inserting spaces instead of tabs at the end of 
text information. The /BF switch is the default. 

Deletes audit trails and any trailing spaces or tabs, and truncates the 
text at a specified horizontal position, n. The value n given for the 
beginning position of the audit trail is the default value for this switch. 
See Section 13.5.2.4 for more information about the /CM switch. 

Calculates the checksum value for the edit commands. If you do not 
specify n, SLP reports the value in a message on your terminal. If 
you do specify n and the checksum value that SLP calculates is not the 
same as the one you specified, SLP displays a diagnostic error message. 
The procedure SLP uses to calculate the checksum value for the edit 
commands is described in Section 13.1.2. 



Generates the listing file in double-space format, 
the default. 



The /-DB switch is 
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Table 13-2 (Cont.): SLP Switches 



Switch Fonnat Function 



/NS Does not sequence the Unes in the output file. New lines are indicated 

by the audit trail (if specified). The /NS switch is the default condition 
and overrides the /SQ and /RS switches. 

/RS Resequences the lines in the output file so that the line numbers are 

incremented for each line written to the output file. The /RS switch 
overrides the /SQ switch. 

[/SP] Spools the listing file to the printer. The /SP switch is the default. This 

/-SP svntch applies only if you have the queue management system on your 

system. 

/SQ Sequences the lines in the output file so that the numbers reflect the 

line numbers of the original input file. New lines added to the file have 
the same number as the preceding line. This allows the MACRO-11 
Relocatable Assembler to output listing files that contain the original 
line numbers, thus easing the process of updating correction files. 

If you specify a listing file, SLP preserves the line numbers of the input 
file but does not display numbers for the new lines that have been 
inserted. 

/TR Reports truncation of lines by the audit trail. If line truncation occurs, 

you will get a diagnostic error message. There is no default value for 
this swdtch. 

In the listing file, a question mark ( ? ) replaces the period ( . ) in the line 
number of the lines that were truncated. 

13.5.2 Controlling the Audit Trail 

The /AU svtdtch allows you to generate, suppress, and set the length and contents of the audit 
trail. To suppress generation of the audit trail, specify the /-AU switch in either the input or 
output file specification. 

For example, either of the following command lines generates an output file with no audit trail: 
DKl : MYFILE . MAC ; 3/-AU , LP . LST : =MYFILE . MAC ; 2 
DKl : MYFILE . MAC ; 3 . LP . LST : =MYFILE . MAC ; 2/-AU 
LP.LST will be spooled automatically. 

By default, SLP automatically generates an audit h-ail; that is, you need not explicitly specify 
the /AU switch in your command line (unless you want to specify the beginning position and 
length of the audit trail). 
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13.5.2.1 Setting \Jne Position and Lengtti of the Audit Trail 

You can set the beginning position of the audit trail and the length of the audit trail by using 
the /AU switch. 

Format 

/AU:position:length 

Parameters 

position 

Specifies a number, less than or equal to 132io, designating the beginning character position 
of the audit trail on the line. SLP rounds this value to the next highest tab stop (a multiple 
of 8). The default value for position is 8O10. 

Note 

Numeric values given for switches default to octal. Decimal values must 
be followed by a period ( . ). The default position for the audit trail is 8O10 
and its default length is 810; no more than 14io characters may be specified. 
(See Section 13.5.2 for more information about the audit trail.) 

length 

Specifies the length of the audit trail. The default value for length is 810 characters; no 
more than 14io characters may be specified. 

Example 



MOV 


#BUF1,R0 


MOV 


»SIZ.R1 


CALL 


READ 


TST 


R2 


BEQ 


END 



Shows the contents of the input file. 

SLP>MYFILE.MAC:2/AU:30. :10./TR.MYFILE.LST/-SP=MYFILE.MAC;1 [RET] 

-2,.+l./;CHANGE001/ \Mi 

CMP (R1) + .B [Ml 

DEC R2 iRgfl 

/ 

Specifies the beginrung position and length of the audit trail when used with the previous input 
file. 

The listing file MYFILE.LST;! resulting from SLP processing is as follows: 



1. 


MOV 


#BUF1,R0 




2. 


CMP 


{R1)+,B 


;CHANGE001 


3. 


DEC 


R2 


:CHANGE001 


4. 


TST 


R2 


;**-2 


5. 


BEQ 


END 
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13.5.2.2 Changing the Value of the Audit Trail 

To change the value of the audit trail, specify the format shown next. 

Format 

-[locatorl],[locator2],/;new value/ 

Porometers 

locator! 

Specifies, in any of the forms of the locator fields described in Section 13.3, the line where 
SLP is to begin deleting lines. 

locator2 

Specifies, in any of the forms of the locator fields described in Section 13.3, the last line to 
be deleted. 

new value 

Specifies the new audit trail value. 

Example 



MOV 


#BUF1.R0 


MOV 


«SIZ,R1 


CALL 


READ 


TST 


R2 


BEQ 


END 


CLR 


Rl 


MOV 


R2,NUMC 


CMPB 


(RO)+,A 


BNE 


20$ 


INC 


Rl 



Shows the contents of the input file. 

SLP>MYFILE.MAC:2/AU:48. :10./TR,MYFILE.LST/-SP=MYFILE.MAC;1 \M] 

-3 [Ml 

CMP (R1) + .B IM] 

-4,4 \M\ 
DEC R2 \M} 

-6,./:JM010/ IM] 
INC R3 FRETI 

-9../;BJ008/ \M] 
BEQ 10$ [m 

/ 

Inserts a line after line 3, deletes and replaces line 4, and inserts new lines after lines 6 and 9 
with new audit trail values in the previous input file. 

The listing file (MYFILE.LST) resulting from SLP processing appears, as follows: 
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1. 


MOV 


#BUF1.R0 


2. 


MOV 


#SIZ,R1 


3. 


CALL 


READ 


4. 


CMP 


(R1) + ,B 


5. 


DEC 


R2 


6. 


BEQ 


END 


7. 


CLR 


Rl 


8. 


INC 


R3 


9. 


MOV 


R2,NUMC 


10. 


CMPB 


(RO)*.A 


11. 


BNE 


20$ 


12. 


BEQ 


10$ 


13. 


INC 


Rl 



; **NEW** 
; **NEW** 
; **-l 

;JM010 



;BJ008 



13.5.2.3 Temporarily Suppressing tlie Audit Traii 

You can temporarily suppress the generation of the audit trail by using the backslash operator 
(\). You can then reenable audit-trail processing with the percent sign (%) operator. (You 
cannot enable audit-trail processing with this operator if you have specified the /-AU switch in 
the SLP command line.) 

Both operators are entered in the command input. The backslash is specified in column 1 of 
the line that precedes those commands and/or input files for which you do not want audit-trail 
processing. The percent sign is specified in column 1 of the line that precedes the lines for 
which you do want processing. 

Example 

SLP>BAK.MAC;26/AU/-BF=BAK.MAC;25 [M] 

/ 

-2,2 [RETl 

.IDENT 705.03/ [Rg] 
-23,23 [M] 
; VERSION 05.03 \M] 
-37,, \M} 

J. MATTHEWS ll-NOV-80 |M] 

[RET] 

JMOll CORRECT OOT-OF-BOUNDS CONDITION FOR INPUT-BUFFER [M] 

SIZE \m] 

1. m\ 

-106, 106,/; JMOll/ [Rg] 

CMP #132. ,R3 ; IS INPUT-BUFFER SIZE IN RANGE? [M] 

BLT 30$ ; IF LT, NO [M] 

. w\ 

. (Ml 

. [RET] 
/ 

Shows the lines between the backslash and the percent sign are not affected by audit-trail 
processing. The lines following the percent sign are affected. 
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13.5.2.4 Deleting the Audit Trail 

The /CM switch allows you to delete audit trails and trailing spaces and tabs from a file. The 
/CM switch applied to the output or input file specification accepts a numeric argument that 
specifies the beginning position of an audit trail or other text string to be deleted. The default 
for this argument is the position argument given for the /AU switch (or its default, decimal 80). 
This value is rounded to the next highest tab stop before use. 

When processing an input line, SLP first truncates the text to the next highest tab stop after the 
position specified, and it then deletes any trailing spaces or tabs. The remaining text is copied 
to the output file. 

Format 

/CM[:n] 

Parameter 

n 

Specifies a number designating the beginning character position of the audit trail (or other 
text) to be deleted. 

Examples 

SLP>SLPR11 .MAC; 12/CM: 119. =SLPR11 .MAC; 11 IM] 
/ 

Truncates the input lines to a length of 120io characters. The specified length is rounded up to 
the next highest tab stop and the audit trail begins at column 121io. Trailing spaces and tabs 
are deleted before each line is copied to the output file. 

SLP>SLPR1 1 . MAC : 12=SLPR1 1 . MAC ; 1 1/CM [M] 
/ 

Truncates input lines to the defauh position of the audit trail, column 8O10. 

13.6 SLP Messages 

SLP messages are divided into three groups: informational, fatal error, and diagnostic. Diagnostic 
and fatal error messages describe a condition that caused SLP to terminate the processing of a 
command. When this occurs, SLP returns to the level of command input. For example, when 
the command is entered in response to the SLP prompt, SLP will issue a fatal or diagnostic 
error message and prompt you with the SLP prompt, as follows: 

SLP>comiiiaiiclline 
SLP — message 
SLP> 

Fatal error messages are issued to your terminal in the following format: 

SLP -- *FATAL* - message 

Diagnostic error messages are issued to your terminal in the following format: 

SLP -- *DIAG* - message 
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If a diagnostic or fatal error occurs during the processing of an indirect command file, the 
command file is closed, the error message — followed by the command line in error — is issued 
to your terminal, and SLP returns to the level of command input. 

The SLP error message text may be followed on the next line by the command line or command 
line segment that caused the message. For example: 

SLP — *FATAL*- Illegal switch or filespec 
SHIRLEY. MAC ;2/CF 

SLP error message text may also be followed on the same line by the name of the file with 
which the error is associated. For example: 

SLP — *FATAL*- Open failure line listing file filename 

13.6.1 SLP Informational Messages 

This section lists the SLP informational messages. Following each message is an explanation of 
the error and any recommended user action. 

SLP — Command file checksum Is checksum 

Explanation: By specifying the /CS switch in the command line, you requested SLP to 
calculate the checksum value for the edit commands. 

User Action: This message is for your information only. No user action is required. 

SLP — n lines truncated by audit trail 

Explanation: Line truncation by the audit trail was detected. 

User Action: This message is for your information only. The specified output file is still 
created. (In the listing file, a question mark ( ? ) replaces the period ( . ) in the line number 
of the lines that were truncated. It is possible that audit-trail strings from the input file 
will be truncated by the new audit-trail string, although text strings will not be truncated.) 
Determine where the truncation or truncations occurred. If necessary, modify the command 
file so it contains commands that do not cause truncation. 

13.6.2 SLP Diagnostic Error Messages 

This section lists the SLP diagnostic error messages. Following each message is an explanation 
of the error and the recommended user action to correct the error. 

SLP — 'DIAG*- I/O error command Input file 
or 

SLP — 'DIAG*- I/O error command output file 
or 

SLP — DIAG- I/O error correction Input file fllename 
or 
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SLP — -DIAG-- I/O error line listing file filename 
or 

SLP — 'DIAG- i/O error source output file filename 

Explanation: One of the following conditions may exist: 

• A problem exists on the physical device (for example, the disk is not spinning). 

• The length of the command line was greater than the allowed number of characters. 

• The file is corrupted or the format is incorrect. 

User Action: Determine which condition caused the message and correct that condition; 
then, reenter the command line. 

SLP — DIAG-- Line number error 
commandline 

Explanation: The command line printed contained an illegally specified numeric line locator. 

User Action: Terminate the SLP edit session and refer to the rules for specifying numeric 
line locators in Section 13.3. Correct the error and reenter the command line. 

SLP — 'DIAG- Premature EOF correction input flie tiiename 

Explanation: An out-of-range line locator was specified in an indirect command file or from 
the terminal; for example, -990 was specified for an 800-line file. 

User Action: Terminate the current editing session; then, restart the editing session and enter 
the edit command line with the correct line number specified. 

SLP — -DiAG-- Premature EOF command input flie 

Explanation: This is caused by not terminating SLP command input with a slash (/) or 
by inadvertently pressing CTRL/Z at the terminal, which sends an end-of-file (EOF) to 
SLP before the slash character is read. SLP prompts (SLP> ), indicating that a new file 
specification is expected. 

User Action: Restart the editing session at the point where the CTRL/Z was pressed. 

SLP — -DIAG*- Error In command file filename ctieclcsum 

Explanation: An incorrect value was specified for the command file checksum. If you enter 
the edit command lines directly from the terminal, the command file in the error message 
is CMI.CMD. Thus, the error message will read as follows: 

SLP — *DIAG*- Error in command file CMI.CMD checksum 

User Action: This is a wanung message only. The specified output file is still created, 
although possibly not as intended. 
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13.6.3 SLP Fatal Error Messages 

This section lists the SLP fatal error messages. Following each message is an explanation of the 
error and recommended user action to correct the error. 

SLP — 'FATAL'- Command syntax error 
commandline 

Explanation: The command line format did not conform to sjmtax rules. Open files were 
closed and SLP was reinitialized. 

User Action: Specify the proper syntax and reenter the command line. 

SLP — 'FATAL'- Illegal device name 
commandline 

Explanation: The device specified was not a legal device. Open files were closed and SLP 
was reinitialized. 

User Action: Specify a legal device and reenter the command line. 

SLP — FATAL- Illegal directory 
commandline 

Explanation: The directory was not legally specified. Open files were closed and SLP was 
reinitialized. 

User Action: Specify a legal directory and reenter the command line. 

SLP — 'FATAL'- Illegal error/severity code pi p2 p3 

Explanation: This error message indicates an error in the SLP program. 

User Action: Reenter the command line. If the error persists, submit a Software Performance 
Report (SPR) with the console dialog and any other related information, such as programs 
or listings. 

SLP — 'FATAL'- illegal tile name 
commandline 

Explanation: A file specification was greater than 19 characters in length or contained a 
wildcard (that is, an asterisk (*) in place of a file specification element). Open files were 
closed and SLP was reinitialized. 

User Action: Specify a legal file name and reenter the command line. 

SLP — 'FATAL'- Illegal Get Command Line error code 

Explanation: The system was unable to read a command line. This error message indicates 
an internal system faUure or an error in the SLP program. 

User Action: Reenter the command line. If the error persists, submit an SPR with the console 
dialog and any other related information. 
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SLP — FATAL'- Illegal switch or fliespec 
commandline 

Explanation: This error has occurred for one of the following reasons: 

• The switch was not a legal SLP switch. 

• A legal switch was used in an illegal manner. 

• A file specification could not be parsed. 

User Action: Specify the legal switch or file specification and reenter the command line. 

SLP — •FATAL-- Indirect command syntax error 
commandline 

Explanation: The command line format specified for the indirect command file did not 
conform to syntax rules. Open files are closed and SLP was reinitialized. 

User Action: Specify the proper syntax and reenter the command line. 

SLP — -FATAL- Indirect tile depth exceeded 
commandline 

Explanation: More than three levels of indirect command files were specified in an indirect 
command file. Open files were closed and SLP was reinitialized. 

User Action: Correct the indirect command file and reenter the command line. 

SLP — -FATAL-- Indirect file open failure 
commandline 

or 

SLP — -FATAL-- Open failure correction input file filename 
or 

SLP — -FATAL-- Open failure line listing file tllename 
or 

SLP — -FATAL- Open failure source output file filename 
Explanation: One of the following conditions may exist: 

• The file is protected against an access. 

• A problem exists with the physical device (for example, the device was not on line). 

• The volume is not mounted. 

• The specified file directory does not exist. 

• The named file does not exist in the specified directory. 

• The available Executive dynamic memory is insufficient for the operation. 
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These errors cause opei\ files to be closed and SLP to be reinitialized. 

User Action: Determine which condition caused the message and correct that condition; 
then, reenter the command line. 
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Chapter 14 



File Structure Verification Utility (VFY) 



The File Structure Verification Utility (VFY) for Files- 11 volumes provides the ability to perform 
the following tasks: 

• Check the readability and validity of a file-structured volume (default function). 

• Print the number of available blocks on a file-structured volume (the Free switch (/FR)). 

• Search for files in the index file that are not in any directory; that is, files that are "lost" 
in the sense that they cannot be accessed by file name (the Lost switch (/LO)). (See the 
RSX-llM-PLUS and Micro/RSX I/O Operations Reference Manual for a description of the 
index file.) 

• Validate directories against the files they list (the Directory Validation switch (/DV)). 

• List all files in the index file, showing the file ID, file name, and ov^mer (the List switch 
(/LI)). 

• Mark as "used" all the blocks that appear to be available but are actually allocated to a file 
(the Update switch (/UP)). 

• Rebuild the storage allocation bit map so that it properly reflects the information in the 
index file (the Rebuild switch (/RE)). 

• Restore files that are marked for deletion (the Delete switch (/DE)). 

• Delete bad file headers (the Header Delete switch (/HD)). 

• Perform a read check on every allocated block on a file-structured volume (the Read Check 
switch (/RC)). 

The volume to be verified must be mounted as a Files-11 device. 

There should be no other activity on the volume while VFY is executing. In particular, activities 
that create new files, extend existing files, or delete files should not be attempted while VFY is 
executing a function. 
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Caution 

VFY must not be aborted while an /UP, /RE, /DE, or the /HD switch is being 
processed. Aborting VFV while it is modifying the storage allocation or index 
files can seriously endanger the integrity of that volume. 

14.1 VFY Command Line 

The command line for VFY is shown next. 

Format 

listfile,scratchdev=indev/switch 

Parameter 

listflie 

Specifies the output file specification as follows: 

ddnn : [directory] filename . type ; version 

Refer to Chapter 1 for detailed descriptions of the parameters for file specifications. 

If you do not specify a device, the default for the output listing device is the issuing terminal 
(TI). The default for [directory] is the default directory to which your terminal is set. You 
must, however, specify the file name and file type of the output file. The default version 
number will be the latest version plus one. 

scratchdev 

Specifies the device on which the scratch file produced by VFY is to be written. This 
parameter is in the following format: 

ddnn: 

The scratch file is used by VFY during the verification scan and during the lost fUe scan. It 
is created but not entered in a directory. Therefore, it is transparent to you. The scratch 
file is automatically deleted when VFY is terminated. If you do not specify a scratch device 
the default device is SYO. 

If the user's default system disk is faulty or full, use this parameter to direct the scratch file 
to another device. The scratch file should always be assigned to a volume other than the 
indev volume. The scratch file is not used with the /FR and /LI svntches. 

indev 

Specifies the volume to be verified in the same format as scratchdev. If you do not specify 
the volume, the default is SYO. 

switch 

Specifies the function to be performed by VFY. 

The switches and their functions are summarized in Table 14-1. Detailed descriptions of 
the switches are given in Section 14.1.1. 
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Table 14-1: VFY Switches and Functions 



Switch 



Format Description 



Delete /DE 

Directory Validation /DV 

Free /FR 

Header Delete /HD 



Identify 



/ID 



List 


/LI 


Lost 


/LO 


Read Check 


/RC 


Rebuild 


/RE 


Update 


/UP 



Resets the marked-for-deletion indicators. 

Validates directories against the files they list. 

Prints out the available space on a volume. 

Deletes bad file headers on a volume. The All subs witch 
(/AL) allows the /HD switch to delete bad file headers 
without prompting the user. 

Identifies the VFY version. This switch may be specified on 
a command line by itself at any time. 

Lists the index file by file ID. 

Scans the file structure looking for files that are not in any 
directory. 

Checks the volume to see if every block of every file can be 
read. 

Recovers blocks that appear to be allocated but are not 
contained in a file. 

Allocates blocks that appear to be available but are actually 
allocated to a file. 



14.1.1 VFY Switch Descriptions 

VFY functions are specified vwth svidtches appended to the VFY command line. The switches 
and their functions are summarized in Table 14-1. 

14.1.1.1 Delete 

The Delete switch (/DE) resets the marked-for-deletion indicators in the file header area of files 
that were marked for deletion but never deleted. 

VFY must be running under a system User Identification Code (UIC) and the volume must be 
mounted and unlocked. 

14.1.1.2 Directory Validation 

The Directory Validation switch (/DV) examines each directory on the volume. (VFY considers 
any file on the volume with the file type DIR and a fixed record length of 16 bytes to be a 
directory.) It then reports any errors found that could be attributed to a corrupt directory or a 
nonexistent file listed in the directory. 
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Example 

>VFY DX:/DV [RET] 

The following directory entries were invalid 

[301,333] File ID 13,2,0 DELETED . FIL ; 1 - file not found 

[301,333] File ID 12345.3.0 CORRUPTED . FID ; 1 - file not found 

[301,333] File ID 14,2,0 GARBAGE . VER ; 123456 - invalid version number 

[301,333] File ID 15.1,444 RELVDLNEZ . ERO ; 1 - reserved field was non-zero 

4. Invalid directory entries were found 

Shows that invaUd entries were found. Directory entries may be invalid due to the following 
conditions: 

File not found 

The file was either deleted without the corresponding directory entry being removed or the 
file ID field in the directory entry was corrupted. If the file does exist, it cannot be accessed 
with this directory entry. 

Remove the directory entry by using the Peripheral Interchange Program (PIP) switch 
Remove (/RM). 

Invalid version number 

The directory entry was corrupted. If the file does exist, it cannot be accessed with this 
directory entry. 

Remove version zero of the file with the PIP switch /RM. 

Resented field was nonzero 

The third word of the file ID field in a directory entry is a reserved field and should always 
be zero. Remove the directory entry with the PIP switch /RM and then reenter it with the 
PIP switch Enter (/EN). 

14.1.1.3 Free 

The Free switch (/FR) displays the available space on a specified volume with the following 
message: 

dev: has nnnn. blocks free, nnnn. blocks used out of nnnn. 

14.1.1.4 Header Delete 

The Header Delete switch (/HD) recognizes all bad file headers on a volume. If you specify 
the /AL subswitch, all bad file headers will automatically be deleted. 

If you do not specify the /AL subswitch, VFY prompts you as follows: 

>VFY DX1:/HD \Mi 

Consistency check of index and bitmap on DXl: 

File ID 000015,000003 007334. DIR;1 owner [7,334] 

Bad file header 
Delete this header [Y/N/Q/G]? 
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NIRET] 

Qua 

GFret] 

# m] 



You may respond as follows: 

Y [ret] Deletes the header and proceeds. 

Does not delete the header and proceeds. 

Does not delete the header and does not proceed. 

Deletes the header and all subsequent bad headers. 

Does not delete the header and proceeds. 
If you give any other response, the following message will appear: 
VFY — Illegal response - try again 

14.1.1.5 Identify 

The Identify switch (/ID) identifies the current version of VFY running on your system. The 
/ID switch can be specified alone on a command line at any time. 

14.1.1.6 List 

The List switch (/LI) lists the index file. The output for each file specifies the file number, file 
sequence number, file name, and owner UlC. 

Example 

VFY>DK:/LI [Ml 
Listing of index on DKO: 



File 


ID 


000001.000001 


INDEXF.SYS.l 


ovmer 


:i,i] 


File 


ID 


000002,000002 


BITMAP. SYS ;1 


owner 


:i,i] 


File 


ID 


000003.000003 


BADBLK.SYS;! 


owner 


:i.i] 


File 


ID 


000004.000004 


000000. DIR;1 


owner 


:i.i] 


File 


ID 


000005.000005 


CORIMG.SYS;! 


owner 


:i.i] 


File 


ID 


000006.000006 


001001. DIR:1 


owner 


:i.i] 


File 


ID 


000007.000007 


001002. DIR;1 


owner 


:i.2] 


File 


ID 


000010,000010 


EXEMC.MLB;! 


owner 


:i,i] 


File 


ID 


000011.000011 


RSXMAC.Sh(L;l 


owner 1 


:i.i] 


File 


ID 


000012.000012 


NODES. TBL;1 


owner 


:i.i] 


File 


ID 


000013.000036 


QI0SYM.MSG;311 


owner 


:i.2] 


File 


ID 


000014,000037 


F4PC0M.MSG;1 


owner 


1.2] 



Lists the index file for DK. 



14.1.1.7 Lost 



The Lost switch (/LO) scans the file structure looking for files that are not in any directory and 
cannot be referenced by file name. (VFY considers any file on the volume with the file type 
DIR and a fixed record length of 16 bytes to be a directory.) A list of the files is produced, and, 
if the "lost file directory" [1,3] exists on that volume, the files will be entered in that directory. 
If an I/O error occurs, however, on a directory file operation, the files will not be entered into 
directory [1,3]. The following error message will appear: 

Failed to open directory file 

Error code -16. - directory [301,333] 

As a result, no files will be entered in [1,3] 
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14.1.1.8 Read Check 

The Read Check switch (/RC) checks to ensure that every block of every file on a specified 
volume can be read. 

The optional parameter [:n] is the blocking factor that indicates the number of file blocks to be 
read one at a time. The default value is the maximum number of blocks available in VFY's 
buffer area. The buffer area available may be increased by installing VFY in a larger partition. 
Four blocks are available when VFY is installed in an 8K partition, and four blocks are added 
for each IK increment. 

For the fastest read check, the maximum block factor should be used. Whenever an error is 
encountered, each block of the portion in error is reread to determine which data block or 
blocks cannot be read. 

When an error is detected, a file identification line is displayed in the following format: 

File ID nn.nn filename. type; version, n blocks used/n blocks allocated 

Following this line, an error message is displayed. If a blocking factor other than 1 is in use, 
an error message in the following form will be issued: 

Error starting at VBN nl.n2 LBN nl,n2 - error code - n 

Following the first error message, there should be one or more error messages indicating the 
exact block or blocks in error. The second error message line or lines will be in the following 
form; 

Error at VBN ni,n2 LBN nl,n2 - error code - n 

If an "Error starting at" message is displayed without one or more "Error at" messages, a 
multiblock read operation on the selected device has failed, but the data blocks appear to be 
individually readable. 

If the Virtual Block Number (VBN) of the unreadable block listed in the "Error at" message is 
beyond the block-used count, the data portion of the file is readable. 

The negative number printed after the "Error code" message is usually -4 to indicate a device 
parity error. Other error codes are contained in the BSX-llM-PLUS and Micro/RSX I/O 
Operations Reference Manual. 

14.1.1.9 Rebuild 

The Rebuild switch (/RE) recovers lost blocks; that is, blocks that appear to be allocated but 
are not contained in any file. 

Multiply-allocated blocks must be deleted from the file structure before the /RE switch can take 
effect. 

You must run VFY under a system UIC and unlock the volume. The scratch file should be on 
another volume. 
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14.1.1.10 Update 

The Update switch (/UP) allocates blocks that appear to be available but are actually allocated 
to a file. 

Files with multiply-allocated blocks must be deleted from the file structure before the Update 
switch can take effect. 

You must run VFY under a system UIC and unlock the volume. The scratch file should be on 
another volume. 

14.2 VFY Mode Of Operation 

VFY normally operates in read-only mode, where the scratch file, if required, is on another 
device. VFY requires write access under the following conditions: 

• If the /UP or /RE switch is used, VFY requires write access to the storage allocation map 
([0,0]BITMAP.SYS). 

• If the /DE or /HD switch is specified, VFY requires write access to the index file 
([0,0]INDEXF.SYS). 

• If the /LO switch is specified and lost files are found, VFY requires write access to the User 
File Directory (UFD) [1,3], which is the directory containing "lost" files. 

If write access to the volume index or bit map files is required for the desired operation, the 
user must mount the unlocked volume by using the Monitor Console Routine (MCR) or Digital 
Command Language (DCL) command MOUNT. 

VFY may be run under any User Identification Code (UIC) if only read access is required. If 
write access is required, VFY must run under a system UIC. 

14.3 VFY Validity Checl< 

VFY checks the readability and validity of the volume mounted on the specified device. This 
function is the default function and entails reading aU the file headers in the index file and 
ensuring that all the disk blocks referenced in the map area of each file header are allocated to 
that file in the volume bit map. 

The volume may be write-protected if it is not the system volume or if the required scratch file 
is directed to another file-structured volume. 

Format 

[listfile,scratchdev=]indev 

Example 

>VFY DRO: 

Consistency check of index and bitmap on DRO: 

Index indicates 114524. blocks free, 17156. blocks used out of 131680. 
Bitmap indicates 114524. blocks free, 17156. blocks used out of 131680. 

Checks the validity and readability of of DRO. 
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14.4 Files Marked for Deletion 

If a file has been marked for deletion but the deletion process was not completed, you can 
either restore the file, if you still need it, or you can delete the file to recover the space it was 
occupying. This situation only occurs when the system crashes during file processing. Once 
files have been restored or deleted, run VFY with the /RE switch to assure the consistency of 
the volume's storage allocation bit map. 

14.4.1 Restoring a File Marlced for Deletion 

To restore a file marked for deletion, mount the disk volume by using the MCR or DCL 
command MOUNT and the /UNL switch. 

Example 

>MOU DKO:/UNL [RET] 

Shows the MOUNT command and the /UNL switch. After entering the conraiand line, run 
VFY and specify the /DE switch to reset the marked-for-deletion indicators in file headers. 
Once the delete indicator has been reset, run VFY specifying the /LO switch to scan the entire 
file struchire. 

The deletion process may have proceeded partially and a portion at the end of the file may be 
missing. This condition can be detected by a directory listing obtained by using the PIP Full 
Format subswitch (/FU). 

14.4.2 Deleting a File Marked for Deletion 

Files that are marked for deletion can be deleted directly with PIP once their unique file ID 
has been obtained by doing a validity check. The file ID appears as the first entry in the file 
identification line that precedes each list of file errors (see Section 14.5). The following example 
shows how the file ID is used with PIP to delete a file. 

Example 

>PIP /FI:12:20/DE [Ml 

Deletes the file with file ID 12,20 from the system device. PIP issues the following error 
message: 

PIP — Failed to mark file for delete-no such file 

Since the file system denies the existence of files already marked for deletion, the file is deleted. 

14.4.3 Deletion of Bod File Headers 

If the volume contains bad file headers, it is advisable to delete them first by using the /HD 
switch before you address the problem of multiply-allocated or free blocks. Deleting bad 
file headers may free the blocks that were contained in the files with the bad headers. See 
Section 14.1.1.4 for a description of the /HD switch. 
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14.4.4 Deletion of Multiply-Allocated Blocks 

If the file structure contains multiply-allocated blocks, it is necessary to delete files until there 
are no such blocks. An automatic rescan of the volume identifies which files share which blocks. 
This rescan lists the 'files that contain the multiply-allocated blocks. Use this information to 
determine which, if any, of the files can be saved and then delete the rest with the PIP delete 
function. 

After the files have been deleted, VFY should be run once again to ensure that all of the files 
containing multiply-allocated blocks have been deleted. 

14.4.5 Elimination of Free Blocks 

Once there are no multiply-allocated blocks, the next concern is the elimination of blocks that are 
marked as free in the storage allocation bit map but are actually allocated to a file. To reallocate 
these blocks in the storage allocation bit map, run the validity check vfith the /UP switch. This 
allocates all blocks that should have been marked as allocated. See Section 14.1.1.10 for a 
description of the /UP switch. 

When you have no multiply-allocated blocks and no blocks marked as free that are actually in 
use, the file structure is safe for writing new files and extending existing files. Files may have 
data blocks that have been overwritten as the result of multiple allocation. 

14.4.6 Recovering Lost Blocks 

To determine whether any blocks have been lost on a file-structured volume, examine the last 
two lines of output from the VFY Validity Check (Section 14.3). The last two lines of output 
give the free space on the volume. The first line reports the amount of available space according 
to the index file (that is, the number of blocks that are not in use by any file in the index file). 
The second line reports the amount of available space according to the storage allocation bit 
map. 

If there are no errors, these two figures should agree. If the index file indicates that more blocks 
are free than the storage allocation bit map indicates, then those blocks are "lost" in the sense 
that they appear to be allocated but no fUe contains them. Lost blocks can be recovered by 
rerunning the VFY Validity Check and specifying the /RE switch. See Section 14.1.1.9 for a 
description of the /RE switch. 

14.5 VFY Error Messages 

As VFY verifies a volume, error conditions are reported. Errors for a given file are preceded by 
a line that identifies the file in error. 

Format 

File ID nn,mm filename.type;version owner [uic] 

Parameters 

nn.mm 

Represents the unique file identification number assigned to the file by the system at 
file-creation time. 
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filename 

Represents the file name. 

type 

Represents the file tjrpe (for example, OBJ for object file). 

version 

Represents the version number of the file. 

ulc 

Represents the UlC for the file. 

This file identification line is followed by one or more messages. 

The last error message for the file is followed by a summary line for that file. 

Format 

Summary: mulrtnb, free=fb, bad=n 

Parameters 

mb 

Specifies the number of multiple block allocations. 

fb 

Specifies the number of blocks marked free that should have been allocated. 

n 

Specifies the number of errors encountered in the the map area of the file header. 

If the output for VFY is directed to a terminal and you do not wish to see the error messages 
for a given file, press CTRL/O. This terminates the listing of error messages for that file; that is, 
all messages but the summary line. 

Error messages describe a condition that may cause VFY to terminate the processing of a 
command. If this occurs, VFY returns to the highest level of command input. For example, if 
the command is entered in response to the Monitor Console Routine (MCR) prompt, VFY will 
issue the error message, exit, and prompt you with the MCR prompt, as follows: 

>VFY commandline 
VFY — message 
> 

If the command is entered in response to the VFY prompt, VFY will issue an error message and 
prompt you with the VFY prompt, as follows: 

VF Y> commaacH ine 
VFY — message 
VFY> 
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The VFY error messages, their explanations, and suggested user actions are as follows: 

Bad block number n,m 

Explanation: The specified block number was found in the header for this file but is illegal 
for the device (out of range). This indicates a corrupted file header. 

User Action: Specify a legal block number and reenter the command line. 

Bad file header 

Explanation: VFY checks on the validity of the file header indicate that the header has been 
corrupted. 

User Action: No user action is requred. 

Block is marked free n,m 

Explanation: The specified LBN is allocated to the indicated file but is not marked as allocated 
in the storage allocation map (see Section 14.4.5). 

User Action: No user action is required. 

VFY — Command syntax error 

Explanation: The command, as entered, does not conform to command syntax rules. 
User Action: Reenter the command line with the correct sjnitax specified. 

VFY — Close failure on bit map 
or 

VFY — Close failure on index file 
or 

VFY — Close failure on temporary file 
or 

VFY — Close failure on listing (lie 

Explanation: One of the following conditions may exist: 

• The device is not on line. 

• The device is not mounted. 

• The hardware has failed. 

User Action: Determine which of the above conditions caused the message and correct that 
condition; then, reenter the command line. 
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VFY — Failed to allocate space for temp die 

Explanation: The volume specified for the temporary scratch file is full. 

User Action: Use PIP to delete unnecessary files and rerun VFY, or specify another volume 
as the scratch device when you reenter the command. 

VFY— Failed to attach device 
or 

VFY — Failed to detach device 

Explanation: The list file specified a terminal device. VFY was not able to attach or detach 
the device. 

User Action: Reenter the command line with a list file device that can be attached or 
detached. 

VFY — Failed to close directory (lie 

Explanation: One of the following conditions may exist: 

• The device is not on line. 

• The device is not mounted. 

• The hardware has failed. 

User Action: Determine which of the above conditions caused the message and correct that 
condition; then, reenter the command line. 

VFY— Failed to enter file 

Explanation: One of the following conditions may exist: 

• VFY is not running under a system UIC. 

• The device is not on line. 

• The device is not mounted. 

• The hardware has failed. 

User Action: Determine which of the conditions caused the message and correct that 
condition; then, reenter the command line. 

VFY— Failed to find INDEXF.SYS; 1 in MFD - will open index by file ID 1 , 1 
or 

VFY— Failed to find BITMAP.SYS;! in MFD - will open bit map by file ID 2.2 
Explanation: The Master File Directory (MFD) has been corrupted. 
User Action: Copy the disk by using the BRU utility (see Chapter 3). 
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VFY — Failed to open directory file 
or 

VFY — Failed to open file for read ctieck 

Explanation: One of the following conditions may exist: 

• VFY is not running under a system UIC as it should be. 

• The named file does not exist in the specified directory. 

• The volume is not mounted. 

• The specified file is read protected. 

• The specified file does not exist. 

User Action: Determine which of the above conditions caused the message and correct that 
condition; then, reenter the command line. 

File Is mari<ed for delete 

Explanation: A system failure occurred while the specified file was being deleted. The 
deletion was not completed and the file header still exists (see Section 14.4). 

User Action: No user action is required. 

Header map error 

Explanation: VFY detected an error in the header map area that also indicates a corrupted 
file header. 

User Action: No user action is required. 

VFY— illegal device 

Explanation: The input device specified is something other than a disk or DECtape. 
User Action: Reenter the command line with a mounted Files-1 1 device specified. 

VFY— Illegal switch 

Explanation: The switch specified is not a valid VFY switch or a valid switch is used illegally. 
User Action: Reenter the command line with the correct switch specified. 

VFY — Illegal response - try again 

Explanation: A response was entered that was not legal. 
User Action: Enter a legal response. 

VFY — I/O error on input file 
or 

VFY — I/O error on output file 
or 
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VFY — I/O error reading directory file 
or 

VFY — I/O error writing die header 

Explanation: One of the following conditions may exist: 

• The device is not on line. 

• The device is not mounted. 

• The hardware has failed. 

User Action: Determine which of the above conditions caused the message and correct that 
condition; then, reenter the command line. 

I/O error reading file header-error code -32 

Explanation: VFY failed to read the file header for the specified file ID. The device is not 
mounted or is off line, or the hardware has failed. 

User Action: No user action is required. 

Multiple allocation n,m 

Explanation: The specified (double-precision) logical block number (LBN) is allocated to 
more than one file. If this error occurs, a second pass is automatically taken which will 
indicate all files that share each multiply-allocated block. The second pass is taken after all 
file headers have been checked (see Section 14.4.3). 

User Action: No user action is required. 

VFY — No dynamic memory available - Partition too small 

Explanation: VFY does not have enough buffer space to run. 
User Action: Run VFY in a larger partition (8K minimum). 

VFY — Open failure on bit map 
or 

VFY — Open failure on Index file 
or 

VFY — Open failure on listing file 
or 
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VFY — Open failure on temporary tile 

Explanation: One of the following conditions may exist: 

VFY is not running under a system UIC as it should be. 

The named file does not exist in the spedfied directory. 

The volume is not mounted. 

The specified file is read protected. 

The specified file does not exist. 

User Action: Determine which of the above conditions caused the message and correct that 
condition; then, reenter the command line. 

VFY— Storage control block (VBNl of BITMAP.SYS) is corrupted 

Explanation: The Storage Control Block is corrupt. This is harmless, because only VFV and 
PIP (using the Free switch (/FR)) can examine the block. 

User Action: Copy the disk by using BRU or DSC (see Chapter 3 or 6 respectively). 

VFY — They are still lost, could not find directory 

Explanation: Directory [1,3] did not exist on the volume. Directory [1,3] is the "lost files' 
directory. VFY enters all files found by the /LO switch into this directory. 

User Action: Use the MCR command UFD or the DCL command SET DEF to enter directory 
[1,3] on the volume. 
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change. For information on TKB maps, see the RSX-llM-PLUS and Micro/RSX Task Builder 
Manual. For information on MACRO-11 listings, see the PDP-11 MACRO-11 Language Reference 
Manual. 

15.1 ZAP Command Line 

You invoke ZAP by using any of the methods described in Chapter 1. However, you cannot 
enter a file specification on the same line that you use to invoke ZAP unless the file is an 
indirect command file (see Section 15.1.2). 

The ZAP command line format is shown next. 

Format 

ddnn:[directory]filename.type;version/switch 

Refer to Chapter 1 for detailed descriptions of the parameters for file specifications. 

The ZAP switches are summarized in Table 15-1. The /LI switch is described in detail in 
Section 15.1.1. The /AB and /RO switches are described in detail in Section 15.2. 

The default file type is TSK. After you enter the file specification, ZAP prompts with an 
underscore (_). 

You terminate ZAP by entering the X command (explained in Section 15.6.1). This command 
exits you from ZAP and returns control to your command line interpreter (CLI). 

Table 15-1: ZAP Switches 

Switch Format Function 

Specifies absolute mode. 

Displays the overlay segment table for an overlaid task image file. 

Specifies read-only mode. 

15.1.1 List Switch 

When using ZAP in task image mode (but not absolute), you can also specify the List switch 
(/LI). The /LI switch directs ZAP to display the overlay segment table for the task image file 
on disk that you are working with. The overlay segment table lists the starting disk block 
and address boundaries for each overlay segment in the file. The segment table lists are in a 
different format for each type of task image file. (The formats for each type of task image file 
are discussed later in this chapter.) You use this table and TKB map to locate the task segments 
being changed. 

The /LI switch displays the overlay segment boundaries in the format shown next. 

Format 

block:lower-upper [name] [type] 



Absolute Mod* 


i /AB 


List 


/LI 


Read-Only 


/RO 



15-2 Task/File Patch Program (ZAP) 



Parameters 

block: 

Specifies the starting block in octal. 

lower 

Specifies the lower address boundary in octal. 

upper 

Specifies the upper address boundary in octal. 

name 

Specifies the segment name that appears for instruction and data space tasks, manually 
loaded overlays ($LOAD), memory-resident overlays, tasks that link to the library with 
memory-resident overlays, or for any combination of the previous conditions. 

type 

Specifies the description of the segment-type string that appears next to the segment name 
in the segment table. 

The following sections describe the /LI switch formats for the different kinds of task image 
files. Section 15.7 gives examples of the segment table lists. 

15.1.1.1 The /LI Switch and Regular Task Image Files 

For regular task image files (including those mapped to resident and supervisor-mode libraries), 
the /LI switch displays the task's overlay segments in the order of their location in the file. 
Each segment in these files begins on an even block boundary. 

15.1.1.2 The /LI Switch and Multiuser Task Image Files 

For multiuser tasks, the /LI switch lists the starting disk block number and address boundaries 
of each segment. In addition, the address boundaries of the shared read-only segment are 
listed. The block number that is used to reference the multiuser segment is the same as the 
root segment. The multiuser segment is an extension of the root segment. The segment list 
disk block numbers have a corresponding entry in the Task Builder (TKB) map. 

See the RSX-llM-PLUS and Micro/RSX Task Builder Manual for more information on multiuser 
tasks. 

15.1.1.3 The /LI Switch and Resident Libraries 

For resident libraries, the /LI switch displays each of the task's segments as beginning on a new 
block boundary. However, the segments may not actually begin on even boundaries because of 
compression by the Task Builder. Resident libraries can be overlaid, but each overlay segment 
must also be resident in memory. 

To avoid the possibility that two or more segments in a single block could have the same 
virtual address, ZAP treats the resident library in the same way that TKB does. TKB builds the 
library with each segment beginning on an even block boundary, but it then compresses the 
segments in the task file itself. The TKB map is generated before the segments are compressed, 
so the boundaries given in the map do not necessarily correspond to the actual location of the 
segments. 
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The disk block boundaries given in the TKB map file are the ones that ZAP uses to address 
locations in the resident library and that the /LI switch displays in its segment table. They do 
not use the actual starting blocks of the segments. (You should be aware of this when you are 
working with resident libraries in absolute mode. However, also remember that you cannot use 
the /LI switch in absolute mode.) 

You should also note that ZAP cannot know the physical starting addresses for the segments of 
an overlaid resident library because its overlay structure is stored in the S5mibol definition (STB) 
file, not with the task image file itself. For ZAP, each segment's starting address is 000000. 

See the RSX-llM-PLUS and Micro/RSX Task Builder Manual for more information on resident 
libraries. 

15.1.1.4 The /LI Switch and Instruction and Data Space Tasks 

For instruction and data space (I- and D-space) tasks, the /LI switch lists the starting block 
number and the address boundaries of each segment. The 1- and D-space segment may be 
suppressed in the listing when, for example, a segment with only I-space code does not include 
a listing for a D-space segment. If the segments are not suppressed, the segment list disk block 
numbers have a corresponding entry in the TKB map. 

15.1.2 Using Indirect Command Files with ZAP 

An indirect command file contains the specification for the file you want to work with and the 
appropriate ZAP commands. You can specify the indirect command file in the same command 
line in which you invoke ZAP. 

The following sample indirect command file (called CHANGE.CMD) contains ZAP commands. 
The commands will change the default priority of the despooler from 70 to 80 (IZOg). The V 
command (explained in Section 15.6.5) is used to verify that 70 (1068) is what is actually in the 
location to be changed. The command file has the following ZAP commands: 

LPP.TSK/AB 

: 346/ 

106V 

120 

X 

To use the indirect command file, type the following: 

>ZAP eCHANGE [RfT] 

This command invokes ZAP, which then executes the commands in the file. 

The first command used opens the task image file (LPP.TSK) in absolute mode (using the /AB 
switch). The next two commands open the desired location (byte 346 in block 0) and verify 
its contents (106). The next command changes the contents to 120, which will be the new 
default priority for the despooler. The X command exits you from ZAP and returns control to 
your CLl. 
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15.2 ZAP Operating Modes 

ZAP provides two addressing modes and two access modes. The addressing modes are task 
image mode and absolute mode. Task image mode is the default mode. The access modes are 
read/write mode and read-only mode. Read/write is the default mode. Either addressing mode 
can be used with either access mode. The modes and their associated switches are as follows: 

Task image mode This is the default addressing mode for ZAP. In this mode, addresses in ZAP 
command lines refer to addresses in the task image file as they are shown in 
the TKB map for the file. See Section 15.3.2.1 for more information on using 
task image mode. 

Absolute mode ZAP uses the addresses you enter in ZAP command lines as absolute byte 
addresses within the file. Absolute mode is specified with the /AB switch. 
You must use absolute mode for any files that are not task images. See 
Section 15.3.2.2 for more information on using absolute mode. 

Read/write mode This is the default access mode for ZAP. In this mode, ZAP opens a file for 
reading and/or modification. 

Read-only mode ZAP opens a file for reading but not modification. That is, you can execute 
ZAP functions that change the contents of locations, but these changes are 
not actually made to the file. When ZAP exits, the original values in the file 
are still there. Read-only mode is specified with the /RO switch. 

15.3 Addressing Locations in Files 

To address locations in a file, ZAP provides two addressing modes (task image and absolute, 
described above) and a set of internal registers, which includes eight Relocation Registers. This 
section first introduces the concept of relocation biases and the use of the Relocation Registers; 
then, it explains how to use the addressing modes. 

15.3.1 Relocation Biases 

When MACRO-11 generates a relocatable object module, the base address of each program 
section of the module is 000000. In the assembly listing, all locations in the program section 
are shown relative to this base address. 

TKB links program sections to other program sections by mapping the relative addresses applied 
by the assembler to the physical addresses in memory (for unmapped systems) or to virtual 
addresses (for mapped systems). 

Many values within the resulting task image are biased by a constant whose value is the 
absolute base address of the program section after the section has been relocated. This bias is 
called the relocation bias for the program section. 

ZAP's eight Relocation Registers, OR to 7R, are generally set to the relocation biases of the 
program sections to be examined. This allows you to refer to a location in a module by the 
same relative address that appears in the MACRO-11 listing. The addressing modes help you 
calculate the relocation biases. 
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15.3.2 ZAP Addressing Modes 

As explained in Section 15.2, ZAP's two modes for addressing locations in a file are task image 
mode and absolute mode. Task image mode is the default mode for ZAP. The next two sections 
explain how to use these modes. 

The following example shows excerpts from a MACRO-11 listing of the module MYFILE and 
a TKB map. These excerpts and the accompanying text show how to use ZAP in task image 
mode. 

Example 



71 000574 


032767 


OOOOOOG 


OOOOOOG 


BIT 


#FE.MUP,$FMASK 


72 000602 


001002 








BNE 


2$ 


73 000604 


000167 


000406 






JMP 


30$ 


74 000610 


016700 


OOOOOOG 




2i 


1: MOV 


$TKTCB.RO 


75 000614 


016000 


OOOOOOG 






MOV 


T.UCB(RO),RO 


76 000620 


010067 


177534 






MOV 


RO.UCB 


77 000624 


032760 


OOOOOOG 


OOOOOOG 


BIT 


#U2.HLD.U.CW2(R0) 


Shows the assembled instructions from 


a MACRO- 


-11 source listing. 


R/W MEM 


LIMITS: 


120000 123023 


003024 


01556 . 




DISK BLK 


LIMITS: 


000002 000005 


000004 


00004. 





MEMORY ALLOCATION SYNOPSIS: 
SECTION 

BLK.:(RW.I.La,REL,CON) 

$$RESL : (RW , I . LCL . REL . CON) 



TITLE IDENT FILE 



120232 002546 01382. 
120232 002244 01188. 
122476 000064 00052. 
123000 000024 00020. 



MYFILE 
FMTDV 



01 
01 



MCR.0LB;1 
MCR.0LB;1 



Shows the lines from a TKB map. 

Using information from the TKB map, you can address locations in the task image file as they 
appear in the MACRO-11 listing. 

You can determine, from the TKB map, the block number and byte offset for the beginning of 
the file you want to change. The disk-block-limits line lists block 2 as the block where the 
program code begins. The synopsis lists byte offset 120232 as the beginning of the file MYFILE. 
To address location 574 in the MACRO-11 listing in task image mode, specify the following 
command line: 

2:120232+574/ \M} 

ZAP responds by opening the location and displaying its contents as follows: 

002:121026/ 032767 

Section 15.4 describes the ZAP command line formats. 
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15.3.2.1 Using the Task Image Addressing IVIode 

In task image mode, ZAP allows you to address locations in a task image file by using the 
addresses the MACRO-11 assembler displays in its listing and the starting block number and 
byte offset listed in the TKB map. Unlike absolute mode, task image mode is useful for working 
with locations in an overlaid file because TKB and ZAP perform the calculations necessary to 
relate the file's disk structure to its run-time memory structure. 

15.3.2.2 Using the Absolute Addressing Mode 

In absolute mode, ZAP processes the addresses you enter in the command lines as absolute 
byte addresses within the £Qe. To use ZAP in absolute mode, invoke ZAP and enter the /AB 
switch with the file specification. 

ZAP interprets the first address in the file you are changing as virtual block 1, location 000000. 
All other addresses you enter are interpreted using this address as the base location. Absolute 
mode aUows you to access all the bytes in a data or task image file as well as the label and 
header blocks of a task image file on disk. However, to modify a disk task image, you must 
know the disk layout of the task image. Generally, absolute mode is practical only for data files 
or for task image files that are not overlaid. 

15.4 ZAP Commands and Command Line Elements 

ZAP commands perform functions that allow you to examine and modify the contents of 
locations in a file. Command lines comprise combinations of the following elements: 

• Commands 

• Internal registers 

• Arithmetic operators 

• Command line element separators 

• The current location S5mibol 

• Location-specifier formats 

The command elements can be combined to perform multiple functions. The function of a 
given command line depends not only on which elements you use, but it also depends on the 
position of one element in relation to the next. 

The following sections describe the ZAP command line elements. Sections 15.5 and 15.6 
describe how to combine the command line elements to execute ZAP functions. 

16.4.1 ZAP Commands 

There are three t)^es of ZAP commands: 

• Open and close location 

• General-purpose 

• RETURN key 

The following sections describe each type of command. 



Task/File Patch Program (ZAP) 15-7 



15.4.1.1 Open and Close Location Commands 

Open/close location commands are nonalphanumeric American Standard Code for Information 
Interchange (ASCII) characters that direct ZAP to perform a sequence of functions. Open/close 
commands specify the following two general sequences of operations: 

• Open a location, display its contents, and store the contents in the Quantity Register (see 
Section 15.4.2) 

• Close the location after (optionally) modifying it and open another location as specified by 
the command 

Section 15.5 describes the format for specifying open/close location commands. 

15.4.1.2 General-Purpose Commands 

ZAP provides six single-character, general-purpose commands. You use these commands for 
calculating displacements, verifying location contents, and exiting from ZAP. You can enter 
some of the commands on the command line with no other parameters. Section 15.6 describes 
the format for specifying these commands. 

15.4.1.3 RETURN Key Command 

Unless there is another value or command on the line, the RETURN key closes the current 
location as modified and opens the next sequential location. ZAP commands take effect only 
after you press the RETURN key. 

15.4.2 ZAP Internal Registers 

ZAP internal registers are fixed storage locations that ZAP uses as registers. These registers 
contain values set by both you and ZAP. ZAP provides the following internal registers: 

Relocation Registers to 7 Provide a means for indexing into a program section to change 
(OR to 7R) the contents of locations in the program section. You load the 

registers with the base address of the program section that has 

been relocated by the Task Builder. 

Constant Register (C) You set this register to contain a 16-bit value, which you can 

specify as an expression in the ZAP command line. 

Format Register (F) Controls the format of the displayed address. If the value of 

the F Register is (the initial value), ZAP displays addresses 
relative to the largest value of any Relocation Register whose 
value is less than or equal to the address to be displayed. If the 
value of the Format Register is not 0, ZAP displays addresses 
in absolute byte format. 

Quantity Register ( Q ) ZAP sets the value in the register to be the last value displayed 

at your terminal. 

To access the contents of a register, specify a dollar sign ($) preceding the register name (in 
this case, C) in the command line. 
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Example 



_$C/fRFn 
$C/ 000000 

Directs ZAP to display the contents of the Constant Register. The slash (/ ) is an open command 
(see Section 15.5). 

15.4.3 ZAP Arithmetic Operators 

Operators are single-character command line elements that define an arithmetic operation. 
Generally, ZAP evaluates these expressions as addresses. Table 15-2 describes the operators. 

You use the operators in expressions in command lines. For example, rather than manually 
adding all the displacements listed in the TKB map, you can specify a location by using the 
following notation: 

_2 : 120000fl70/ iRETl 

This method for calculating such a displacement is faster and more accurate than doing it 
manually. 

Table 15-2: ZAP Arithmetic Operators 

Operator Designation Function 

+ Plus sign Adds a value to another value. Used in an expression that ZAP 

then evaluates as a command line element. 

Minus sign Subtracts a value from another value. Used in an expression that 
ZAP then evaluates as a command line element. 

* Asterisk Multiplies a value by 508 and adds it to another value. Used to 

form a Radix-50 string. 



The following example shows how to use the asterisk ( * ) to form Radix-50 strings. Section 15.4.4 
explains the use of the colon (:) and comma (,) (see Table 15-3); the percent sign (%) is an 
open command and is described in Table 15-4. 

Example 

,0.40/ [RETl 

002:0,000040/ 000001 
_l*33|REn 

/iRJTl 
002:0.000040/ 000103 
-KfRETl 
002:0.000040% A$ 

Opens locations, displays contents, and converts locations. 

The first command opens the locations that are 40 bytes offset from the location address 
contained in Relocation Register and displays in octal format the contents of the new location. 
The location contains the value 000001. The second command converts 000001 to Radix-50 
and adds 33 to the Radix-50 value. The slash ( / ) command again displays in octal the value 
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contained in the offset location. The value is now 103. The percent sign ( % ) command displays 
103 in Radix-50 format. 

15.4.4 ZAP Command Line Element Separators 

ZAP provides separators to delimit one command line element from another. Different separators 
are required depending on the type of ZAP command being executed. See Table 15-3. 

Table 15-3: ZAP Command Line Element Separators 

Separator Description Function 

Comma Separates a Relocation Register specification from another command 

line element. 

; Semicolon Separates an address from an internal register specification. Used in 

expressions that set values for Relocation Registers. 

: Colon Separates a block number base value from a byte offset into the block. 

Used in most of the references to locations in a file. 

15.4.5 ZAP Command Line Location-Specifier Formats 

ZAP has four formats for specifying locations in a command line. Each provides a means of 
indexing into a file. The formats are as follows: 

• Current location symbol 

• byteoffset 

• blocknum:byteoffset 

• n,byteoffset 

15.4.5.1 Current Location Symbol Format 

In command line expressions that ZAP evaluates as addresses, a period ( . ) represents the last 
open location. 

15.4.5.2 Byte Offset Format 

The byte offset format is shown next. 

Format 

byteoffset 

If you are using ZAP in absolute mode, ZAP interprets this specification as a byte offset from 
block 1, location 000000. This format is generally useful only when you are using absolute 
mode. 

Example 

_664/ HH] 

Opens absolute location 664 and displays its contents in octal format. 
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15.4.5.3 Block Number:Byte Offset Format 

The block number format allows you to specify a byte offset from a specific block in the file. 

Format 

blocknum:byteoffset 

You can use this format for addressing locations whether or not you enter the /AB switch with 
the file specification. 

In task image mode, ZAP allows you to enter the block number and byte offset displayed in 
the TKB map. The map gives information on the overlay segments in a task image file. See 
Section 15.3 for more information. 

1 5.4.5.4 Relocotion Register, Byte Offset Format 

The Relocation Register, byte offset format allows you to load a Relocation Register with the 
address of a location. The address is then used as a relocation bias. You can then address byte 
offsets from the address loaded in the Relocation Register. 

The format for addressing locations in a task image file is shown next. 

Format 

n,byteoffset 

Parameter 

n 

Specifies the number of the Relocation Register. 

Example 

_2: 001254 :3R[rEt1 
,3.64/ [RET] 
002:3,000064/ 037334 

Loads an addess and opens a location. 

The first command loads the address 001254 into Relocation Register 3; then, the second 
command opens the location that is 64 bytes offset from block 2, location 001254. The contents 
of that location are 037334. 
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15.5 Using ZAP Open and Close Commands 

This section gives examples of how to use the ZAP open and close commands. These commands 
allow you to open locations in a file, modify those locations, and close the locations. 

Table 15-4 summarizes the open and close commands. 
Table 15-4: ZAP Open and Close Commands 



Character Description 



Function 



/ 



% 



@ 



> 



< 



Slash 

Quotation marks 
Percent sign 
Backslash 
Apostrophe 
RETURN key 



Circumflex 
Up arrow 

Underscore 
Back arrow 

At sign 



Right angle bracket 



Left angle bracket 



Opens a location, displays its contents in octal, and stores 
the contents of the location in the Quantity Register ( Q ). 
If the location is odd, it is opened as a byte. 

Opens a location, displays the contents of the location 
as two ASCII characters, and stores the contents of the 
location in the Quantity Register (Q). 

Opens a location, displays the contents of the location in 
Radix-50 format, and stores the contents of the location in 
the Quantity Register ( Q ). 

Opens a location as a byte, displays the contents of the 
location in octal, and stores the contents of the location in 
the Quantity Register ( Q ). 

Opens a location, displays the contents as one ASCII 
character, and stores the contents of the location in the 
Quantity Register ( Q ). 

Closes the current location as modified and opens the next 
sequential location if no other values or commands are on 
the command line. ZAP commands take effect only after 
you press the RETURN key. 

Closes the currently open location as modified and opens 
the preceding location. 

Closes the currentiy open location as modified, uses the 
contents of the location as an offset from the current 
location, and opens the new location. 

Closes the currently open location as modified, uses the 
contents of the location as an absolute address, and opens 
that location. 

Closes the currentiy open location as modified, interprets 
the low-order byte of the contents of the location as the 
relative branch offset, and opens the target location of the 
branch. 

Closes the currently open location as modified; returns to 
the location from which the last series of underscore (_), 
at sign ( @ ), and/ or right angle bracket ( > ) commands 
began; and opens the next sequential location. 
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15.5.1 Opening Locations In a File 

Use any of the ZAP open commands — slash (/), quotation marks ("), percent sign (%), 
backslash (\), or apostrophe ( ' ) — to open a location in a file. The format ZAP uses to display 
the contents of the open location depends on which operator you use. 

Once you open a location in a given format, ZAP displays in that format any other locations 
you open. For example, if you enter the percent sign ( % ) command, the contents of the open 
location are displayed in Radix-50 format. If you continually press the RETURN key, consecutive 
locations are displayed in Radix-50 format until you change the format by entering a different 
special-character open command. 

15.5.2 Changing the Contents of a Location 

When you open a location with a special-character open command, you can change the contents 
of that location by entering the new value and pressing the RETURN key. 

Example 



/IRETI 
002:120000/ 000000 
44444 [ret] 

j\m 

002:120000/ 44444 

Shows how to open a location, change the value of the location, and close the location. 

The first command, the slash ( / ), displays, in octal format, the contents (000000) of the current 
location. The contents are changed by entering the value 44444. The location is then closed, as 
modified, by pressing the RETURN key. The slash and the RETURN key display the new contents 
of the location (see the last line of example). 

15.5.3 Closing Locations in a File 

ZAP uses the RETURN key and other spedal-character commands for closing a location in a file. 
The close commands perform the following three functions: 

• Close the current location. 

• Direct ZAP to another location (such as the preceding location or a location referred to by 
the current location). 

• Open the new location. 

The following sections give examples of how each command works. 
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15.5.3.1 Closing a Location and Opening the Preceding Location 

Use the circumflex ( " ) or up-arrow command (depending on the type of terminal you are using) 
to close the current location, to direct ZAP to the preceding location, and then to open that 
location. 

Example 

_2: 120100/ [Ml 
002:120100/ 000000 

fRETl 
002:120102/ 000111 

-M] 

002:120104/ 000222 
002:120106/ 000333 
002:120104/ 000222 

Shows how the circumflex or up-arrow command works. 

The RETURN key closes the first three open locations and then opens the next location. The 
circumflex command closes location 120106 and directs ZAP to open the preceding location, 
120104. 

15.5.3.2 Closing a Location and Opening an Offset Location 

Use the underscore (— ) or back-arrow command to close the current location, to direct ZAP to 
use the contents of the current location as an offset from the current location, and then to open 
the new location. 

Example 

_2: 120100/ [M] 
002:120100/ 000000 

fRETl 
002:120102/ 111111 

fRET] 
002:120104/ 222222 

[RET] 
002:120106/ 000022 

[RETl 
002:120132/ 123456 

Shows how the underscore or back-arrow command works. 

The RETURN key doses the first three open locations. The underscore command closes location 
120106, directs ZAP to use the contents (22) of the current location as the offset from the 
current location (120110), and then opens that offset location (120132). 
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15.5.3.3 Closing a Location and Opening an Absolute Location 

Use the at sign (@) command to dose the current location, to direct ZAP to use the contents 
of the just-dosed location as the absolute address of a location, and then to open that location. 

Example 

.2:120100/ [RET] 
002:120100/ 000000 
-[RET] 
002:120102/ 111111 

002:120104/ 120114 
_C[RET] 
002:120114/ 114114 

Shows how the at sign command works. 

The RETURN key closes the first three open locations. The at sign command closes 120104, 
directs ZAP to use the contents (120114) of that location as the absolute address of the next 
location to open, and then opens that location. 

15.5.3.4 Closing o Location and Opening a Bronchi Target Location 

Use the right angle bracket ( > ) command to close the current location, to direct ZAP to use 
the low-order byte of the contents of the just-closed location as a branch offset for the address 
of the next location, and then to open that location. 

Example 

_2: 120100/ [Ml 
002:120100/ 005000 

[RET] 
002:120102/ 005301 

.M] 

002:120104/ 001020 
_>[RET] 
002:120146/ 052712 

Shows how the right angle bracket command works. 

The RETURN key closes the first three open locations. The right angle bracket command closes 
location 120104, directs ZAP to use the low-order byte (020) of its contents as the branch offset 
for the address of the next location (120146), and then opens that location. 

15.5.3.5 Closing a Location and Opening a Previous Location 

Use the left angle bracket ( < ) command to close the current location; to direct ZAP to the 
location where the current series of underscore (_), at sign (@), and/or right angle bracket 
( > ) commands began; and then to open that location. 
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Example 

1202:0R[REt1 
0.10/ [RET] 
002:0.000010/ 005212 

rRETi 

002:0.005224/ 001020 

>[RgTl 
002:0,006266/ 000000 

CfRETl 
002:0.000000/ 000000 



002:0,000012/ 000430 

Shows how the left angle bracket command works. 

The underscore command directs ZAP to location 005224. The right angle bracket command 
directs ZAP to location 005266, and the at sign command directs ZAP to location 000000. The 
left angle bracket command then directs ZAP to location 000012, which is the next sequential 
address after the location where the sequence of commands began. 

15.6 Using ZAP General-Purpose Commands 

This section explains the functions of ZAP general-purpose commands and shows the formats 
for specifying them. The commands are entered in response to the ZAP underscore 
prompt (_). 

Table 15-5 describes the commands. 

Table 15-5: ZAP General-Purpose Commands 

Command Function 

X Exits from ZAP; returns control to your CLl. 

K Calculates the offset in bytes between an address and the value contained in a 

Relocation Register, displays the offset value, and stores it in the Quantity Register 

(Q). 

O Displays the jump and branch displacements from the current location to a target 

location. 

Displays, in octal, the value of the expression to the left of the equal sign. 

V Verifies the contents of the current location. 

R Sets the value of a Relocation Register. 

15.6.1 The X Command 

Use the X command to exit from ZAP and return control to your CLI. 

Format 
X 
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16.6.2 The K Command 

Use the K command to calculate the offset in bytes between an address and the value contained 
in a Relocation Register, to display the offset value, and to store the offset value in the Quantity 
Register (Q). 

Formats 

K 

Calculates the offset in bytes between the address of the currently open location and the value 
of the Relocation Register whose contents are equal to or closest to (but less than) the value of 
that address. 

nK 
Calculates the offset in bytes between the currently open location and Relocation Register n. 

a;nK 

Calculates the offset in bytes between address a and Relocation Register n. 

ZAP responds to the K command by displaying the Relocation Register it used and the offset 
value it calculated in the following format: 

=r eg, offset 

Example 

_2:1172:0R[RFn 
_2 : 1232 : IR [RET] 
_2:1202/fREn 
002:000020/ 000111 
_KfRET] 
=0,000010 
_0.100:lKfRETl 
=1,000040 

Shows how to use the K command. 

The first command sets the value of Relocation Register to 001172. The second command sets 
the value of Relocation Register 1 to 001232. The slash command displays, in octal format, the 
contents of location 001202 (000111). The K command calculates the physical distance (offset) 
between the address of the currently open location (001202) and the value of the Relocation 
Register whose contents are equal to or closest to (but less than) the value of the address. ZAP 
then displays the number of the Relocation Register it used (0) and the offset (00010=001202- 
001172). The last command adds 100 to the address in Relocation Register (001172) and 
then calculates the offset between the new address (001272) and the contents of Relocation 
Register 1 (001232). ZAP then displays the number of the specified Relocation Register ( 1 ) and 
the offset (000040=001272-001232). 
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15.6.3 The O Command 

Use the O command to display the jump and branch displacements from the current location 
to a target location. A jvimp displacement is the offset between the open location and the 
target location. The jump displacement is used in the second word of a jump instruction if the 
instruction uses relative addressing. A branch displacement is the low-order byte of a branch 
instruction, which, when executed, branches to the target location. 

Formats 

aO 

Displays the jump and branch displacements from the current location to the target of the 
branch, a. 

a;rO 
Displays the jump and branch displacements from location a to target location r. 

Example 

0.4534/ [RET] 
0,4534/ 1234 
_45660 [RET] 
.000030 000014 

4534: 45660 [RETI 

_000030> 000014 

Shows how to use the O command. 

The first number (000030) specifies the jump displacement and the second number (000014) 
specifies the branch displacement. 

15.6.4 The Equal Sign Command 

Use the equal sign command (=) to display (in octal) the value of the expression to the left of 
the equal sign. 

Format 

expression= 

Example 



2:30/|RET| 
002:000030/ 000000 

_.+ 177756= [M] 
000006 

Shows how to use the equal sign command. 

The first command displays in octal format the content of location 000030, which is 000000. 
The next command adds 177756 to the address of the currently open location (000030). ZAP 
then displays the value of the specified expression (6=30+177756 or 6=30-22). Note that mm 
equals -1. 
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15.6.5 The V Command 

Use the V command to verify that a location contains a specified value. 

You use the V command to ensure that, before you have ZAP change them, the contents being 
changed are what they should be. The V command is mainly useful in indirect command files 
because ZAP issues an error message and exits if the contents do not match. That way, the 
contents are not changed incorrectly. 

Format 

contentsV 

Example 

0.1200/ \M\ 
6V \Mi 

10 \m] 

Shows how to use the V command; if you were using an indirect command file, you would 
include this sequence of ZAP commands in it. 

ZAP opens the location that is 1200 offset from the value of Relocation Register and ensures 
that the value contained at the location is 6. If so, ZAP changes the 6 to 10. If the value is not 
6, ZAP exits. 

15.6.6 The R Command 

Use the R command to specify the value for a Relocation Register. As explained in Sections 15.3.1 
and 15.4.2, ZAP uses these registers to index into a program section so that you can change 
the contents of locations in the program section. 

Format 

_contents;nR 

Parameter 
n 

Specifies the number of the Relocation Register (0 to 7). 

Example 

_$3R/ [M] 
$3R/ 177777 
-125670 :3R[REn 
_$3R/ \M] 
$3R/ 125670 

Shows how to use the R command. 

The first command accesses the contents of Relocation Register 3, which ZAP displays in octal 
format as specified by the slash. The contents of the register are 177777. The next command 
changes the contents of the register to 125670. The last command again displays the contents 
of the register, which have been changed correctly. 
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15.7 ZAP Examples 

This section gives examples of ZAP usage. The examples show the /LI switch segment table 
format and how you would use some of the ZAP commands. 

Some of the ZAP examples in this section are based on information contained in the following 
excerpts from a sample TKB memory allocation map and from the program code for some of 
the modules in the task. Each example follows the section of program code associated with it. 

1. Excerpts from TKB map are as follows: 

MAINMEO.TSK;! Memory allocation map TKBM40.10 Paget 



Task name 
Partition name 
Identification 
Task UIC 



Memory allocation map TKB M40 . 10 
14-MAR-87 16:01 



...MEO 
GEN 
MOO 

[31 , 102] 

Stack limits: 000300 001277 001000 00512. 
PRO xfr address: 020520 
Task attributes: ID 
Total address windows: 2. 
Task image size : 9184. words, I-Space 
3520. words, D-Space 
Task Address limits: 000000 043647 I-Space 
000000 015507 D-Space 
R-W disk blk limits: 000002 000102 000101 00065. 

MAINMEO.TSK;! Overlay description: 

Base Top Length 



000000 023135 023136 09822. I 

000000 014123 014124 06228. D 

022140 043645 021506 09030. I 

014124 015507 001364 00756. D 

022140 022307 000150 00104. I 

014124 014167 000044 00036. D 

022310 022437 000130 00088. I 

014170 014173 000004 00004. D 

022310 022437 000130 00088. I 

014170 014173 000004 00004. D 

022310 022437 000130 00088. I 

014170 014173 000004 00004. D 

022310 022441 000132 00090. I 

014170 014173 000004 00004. D 

022140 023725 001566 00886. I 

014124 014251 000126 00086. D 



MAINO 

INPUT 

CALC 

AADD 

SUBS 

MULL 

DIW 

OUTPUT 



MAINMEO.TSK;! Memory allocation map TKB M40.10 Page 2 

MAING 14-MAR-87 16:0! 

*** Root segment: MAINO 

R/W mem limits: 000000 023135 023136 09822. I-Space 
000000 014123 014124 06228. D-Space 
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Disk blk limits: 000002 000024 000023 00019. I-Space 

000025 000041 000015 00013. D-Space 

Memory allocation synopsis: 

Section Title Ident File 



. BLK . : (RW . I , LCL , REL , CON) 000300 0002 16 00142 . 

000300 000216 00142. CBTA 04.3 
SYSLIB.0LB;7 



MAINMEO . TSK ; 1 Memory allocation map TKB M40.10 Page 4 
INPUT 14-MAR-87 16:01 

*** Segment: INPUT 

R/W mem limits: 022140 043645 021506 09030. I-Space 

014124 015507 001364 00756. D-Space 

Disk blk limits: 000042 000063 000022 00018. I-Space 

000064 000065 000002 00002. D-Space 



*** Segment: CALC 

R/W mem limits: 022140 022307 000150 00104. I-Space 

014124 014167 000044 00036. D-Space 

Disk blk limits: 000066 000066 000001 00001. I-Space 

000067 000067 000001 00001. D-Space 



*** Segment: AADD 

R/W mem limits: 022310 022437 000130 00088. I-Space 

014170 014173 000004 00004. D-Space 

Disk blk limits: 000070 000070 000001 00001. I-Space 

000071 000071 000001 00001. D-Space 



*** Segment: SUBB 

R/W mem limits: 022310 022437 000130 00088. I-Space 

014170 014173 000004 00004. D-Space 

Disk blk limits: 000072 000072 000001 00001. I-Space 

000073 000073 000001 00001. D-Space 



Page 5 



Page 7 



Page 8 
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Page 9 



*** Segment: MULL 

R/W mem limits: 022310 022437 000130 00088. I-Space 

014170 014173 000004 00004. D-Space 

Disk blk limita: 000074 000074 000001 00001. I-Space 

000075 000075 000001 00001. D-Space 



MAINME0.TSK;1 Memory allocation map TKB M40.10 Page 10 
DIW 14-MAR-87 16:01 

*** Segment: DIW 

R/W mem limits: 022310 022441 000132 00090. I-Space 

014170 014173 000004 00004. D-Space 

Disk blk limits: 000076 000076 000001 00001. I-Space 

000077 000077 000001 00001. D-Space 



Page 11 



*** Segment: OUTPUT 

R/W mem limits: 022140 023725 001566 00886. I-Space 
014124 014251 000126 00086. D-Space 



Disk blk limits: 000100 000101 000002 00002. 
000102 000102 000001 00001. 

Memory allocation synopsis: 

Section 



I-Space 
D-Space 



Title Ident File 



BLK . : (RW , I . LCL ,REL . CON) 



022140 000374 00252. 

022140 000042 00034. SAVAL 

022202 000074 00060. CATS 

022276 000126 00086. CDDMG 

022424 000110 00072. C5TA 



00 
03 
00 
02 



SYSLIB.0LB;7 
SYSLIB.0LB;7 
SYSLIB.0LB;7 
SYSLIB.0LB;7 



For this example, the segment table for task MAINMEO is requested. Note that the segment 
table corresponds exactly to the overlay description list given in the TKB map. The sequence 
of ZAP commands is as follows: 
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>zap[ret] 

ZAP>MAINMEO/LI IMl 

ZAP Version V04.00 COPYRIGHT 

Segment Table 

000002: 000000-022137 MAIND 

000025: 000000-014123 MAINO 

000042: 022140-043647 INPUT 

000064: 014124-015507 INPUT 

000066: 022140-022307 CALC 

000067: 014124-014167 CALC 

000070: 022310-022347 AADD 

000071: 014170-014173 AADD 

000072: 022310-022437 SUBB 

000073: 014170-014173 SUBB 

000074: 022310-022437 MULL 

000075: 014170-014173 MULL 

000076: 022310-022443 DIW 

000077: 014170-014173 DIW 

000100: 022140-023727 OUTPUT 

000102: 014124-014253 OUTPUT 



(c) DIGITAL EQUIPMENT CORPOEATION 1987 

I -space root 
D- space root 

I- and 

D- space 

I- and 

D-space 

I- and 

D-space 

I- and 

D-space 

I- and 

D-space 

I- and 

D-space 

I- and 

D-space 



The first command line invokes ZAP and the second command line requests the segment 
table for the task MAINMEO. The /LI switch directs ZAP to give the starting disk block for 
the root segment of the task (in this example, MAINO) and for each segment overlaid on 
the root of the task. The /LI switch also lists the base and top addresses, plus the segment 
text string for each segment. 

Because this is an I- and D-space overlaid task, there is an I-space root segment and a 
D-space root segment, and each is a part of the root segment of the task MAINO. In this 
example, the I-space root segment begins at disk block 2. The addresses for the I-space 
root segment range from 000000 to 022137. The next line of numbers is for the D-space 
root segment, which begins at disk block 25. The addresses for the D-space root segment 
range from 000000 to 014123. The next line of numbers is for the segment INPUT. That 
I-space segment begins at disk block 42 and the D-space segment begins at disk block 64. 
The I-space addresses range from 022140 to 043647 and the D-space addresses range from 
014124 to 015507. The table continues for the remaiiung overlaid segments in the task 
MAINMEO. 



2. In this example, the contents of a location in another task module (TEST.MAC) are being 
changed. The following excerpt from the module shows the associated code: 

TEST MACRO FILE MACRO M1113 18-MAR-87 07:48 PAGE 8-1 

1269 
1270 
1271 
1272 
1273 



1274 010132 

1275 010134 

1276 010140 

1277 010142 

1278 010146 

1279 010150 



010146 
012704 
005003 

010146 
012704 



041114 



050123 



THIS IS A 


PART OF THE MODULE 




TEST.MAC 


WHICH IS 


EN THE ROOT SEGMENT: 




TEST 


MOV 


Rl.-(SP) 


MOV 


#"LB.R4 


CLR 


R3 


CALL 


$FNDUB 


MOV 


Rl.-(SP) 


MOV 


#"SP.R4 
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The sequence of ZAP commands is as follows: 

_42: 121244; OR [M] 
_0. 10136" [Ml 
042:131402" LB 

-' [M] 

042:131402' L 

_' \M} 

042:131403' B 
_120 [RET] 
_0. 10136" \M} 
042:131402" LP 

The first command line loads the starting address of TEST.MAC (121244 in disk block 
42) into Relocation Register 0. The second command line displays as an ASCII word 
the contents of location 10136 of the module. The contents are LB. The first apostrophe 
command (') displays the first byte of the word (L) and the second command displays the 
second byte (B). The following command line changes the contents of the second byte to 
120, which is the ASCII code for the letter P. The last command displays the new contents 
of location 10136, which are now LP. 

In this example, the contents of a location are also being changed. This time, the location 
is in the module TSTVBl.MAC. The following excerpt is the associated code: 

TSTVBl - TSTVBl MACRO FILE MACRO M1113 18-MAR-87 07:52 PAGE 4-2 

153 
154 
155 

156 ; 

157 000334 005702 

158 000336 001404 

159 000340 052767 000060 172516 

160 000346 000403 

The sequence of ZAP commands is as follows: 

_42: 133470 ;1R[1I] 

1.342/ [RET] 
042:134032/ 000060 

100 [RET] 

1.342/ [RET] 
042:134032/ 000100 

The first command line loads the starting address of TSTVBl.MAC (133470 in disk block 
42) into Relocation Register 1. The second command line displays, in octal, the contents of 
location 342 in the module. The third command line changes the contents of this location 
from 60 to 100. The last command line displays the new contents (again in octal). 



PART OF MODULE TSTVBl.MAC 


WHICH IS ALSO 


IN THE ROOT SEGMENT: 


TEST 


TST 


R2 


BEQ 


70$ 


BIS 


#60 . SR3 


BR 


75$ 
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4. In this example, the operation code (op code) for one of the instructions in another module 
is being changed. The module is TSTCM.MAC, and the following excerpt is the associated 
code: 

TSTCM - TSTCM MACHO FILE MACRO Ml 113 18-MAR-87 07:47 PAGE 3-7 

402 ; PART OF THE MODULE TSTCM.MAC 

403 ; WHICH IS IN THE SEGMENT: TSTCM 

404 ; 

405 001272 073127 177766 ASHC #-10.. Rl 

406 001276 010037 OOOOOG MOV R0.e#KISAK6 

407 001302 062701 140002 ADD #140000+2. Rl 

The sequence of ZAP commands is as follows: 

1 13: 154530 :R2 [ret] 
_2, 1302/ [RET] 
113:156032/ 062701 

162701 [RETl 
.2,1302/ [Ml 
113:156032/ 162701 
_X 

The first command line loads the starting address of TSTCM.MAC (154530 in disk block 
113) into Relocation Register 2. The second command line displays in octal the current 
instruction contained in location 1302. The instruction includes the op code 06 for the 
ADD operation. The third command line changes the op code to 16, which signifies the 
SUBTRACT operation. The fourth command line displays the new contents of the location, 
and the X command ends the ZAP session. 

15.8 ZAP Error Messages 

This section lists the messages generated by ZAP, explains the condition that causes each 
message, and suggests a response to the message. 

Error messages describe a condition that caused ZAP to terminate the processing of a command. 
When this occurs, ZAP returns to the highest level of command input. For example, if the 
command is entered in response to the Monitor Console Routine (MCR) prompt, ZAP will issue 
the error message, exit, and prompt you with the MCR prompt, as follows: 

>ZAP Qindirectcoomiandfile 

ZAP — message 

> 

If an error occurs during the processing of an indirect command file, the command file is closed, 
the error message — followed by the command line in error — is issued to your terminal, and 
ZAP returns to the highest level of command input. 

If the command is entered in response to the ZAP prompt, ZAP will issue the error message 
and prompt you with the ZAP prompt, as follows: 

ZAP>coiii]iiandline 
ZAP -- message 
ZAP> 
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Error messages are issued to your terminal in the following format: 

ZAP -- message 

The ZAP error messages are as follows: 

ZAP — Address not within segment 

Explanation: The address specified was not within the overlay segment specified. 

User Action: Specify the correct address or overlay segment number, and reenter the 
command line. 

ZAP — Cannot be used in byte mode 

Explanation: The at sign (@), underscore (_), and right angle bracket (> ) commands 
cannot be used when a location is opened as a byte. 

User Action: If the location is an even address, open the location as a word. 

ZAP — Error In die specification 

Explanation: The file specification was entered incorrectly. 

User Action: Use the correct file specification and reenter the command line. 

ZAP — Error on command input 

Explanation: An I/O error occurred while a command line was being read. This could be a 
hardware error. 

User Action: Ensure that the hardware is functioning properly. If it is, reenter the command 
line. If not, call your DIGITAL Field Service representative. 

ZAP — I/O error on tasi< image file 

Explanation: An I/O error occurred while the file being modified was being read or vmtten. 
This could be a hardware error. 

User Action: Ensure that the hardware is functioning properly. If it is, reenter the command 
line. If not, call your DIGITAL Field Service representative. 

ZAP — No open iocation 

Explanation: You attempted to modify the contents of a closed location. 
User Action: Open the location to perform the modification. 

ZAP — No sucti internal register 

Explanation: The character following a dollar sign ( $ ) was not a valid specification for the 
internal register. 

User Action: Specify the correct value and reenter the command line. 
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ZAP — No such relocation register 

Explanation: An invalid number was spedfied for a Relocation Register. 

User Action: Relocation Registers are numbered to 7. Any other numbers are illegal. 
Specify a valid Relocation Register number and reenter the command line. 

ZAP — No such segment 

Explanation: The starting disk block was not the start of any segment in the task image file 
on disk. 

User Action: Specify the correct disk block address and reenter the command line. 
ZAP — Not a task Image or no task header 

Explanation: An error occurred while the segment tables were being constructed. Possibly, 
the file is not a task image, the /AB switch was not specified, or the task image is defective. 

User Action: Terminate the ZAP session, and then try invoking ZAP with the /AB switch 
specified. 

ZAP — Not Implemented 

Explanation: You entered a command that is recognized by ZAP, but the command is not 
implemented. 

User Action: Ensure that you entered the command correctly and reenter the command line. 
ZAP — Open failure for task Image file 

Explanation: The file to be modified could not be opened. Possibly, the file does not exist, 
the file is locked, the device is not mounted, or you do not have write-access to the file. 

User Action: Check the file specification for errors. Ensure that the volume is properly 
mounted, or use the Peripheral Interchange Program (PIP) to check your file access privileges 
(see Chapter 12). 

ZAP — Segment table overflow 

Explanation: ZAP does not have enough room in its partition to construct a segment table. 

User Action: Install ZAP in a larger partition or with a larger address space. (See the 
description of the MCR or DCL command INSTALL in the RSX-UM-PLUS MCR Operations 
Manual or the RSX-llM-PLUS Command Language Manual.) 

ZAP — Too many arguments 

Explanation: You entered more arguments on the command line than are allowed. 
User Action: Specify the correct syntax and reenter the command line. 

ZAP — Unrecognized command 

Explanation: ZAP did not recognize the command as entered. 

User Action: Check the syntax of the command you are trying to execute, specify the correct 
syntax, and reenter the command line. 
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ZAP — Verify failure 

Explanation: The V command determined that the contents of a location did not match the 
expected value. ZAP terminates. 

User Action: If applicable, check for errors in the indirect command file. Ensure that the 
contents of the file are what they should be. Locate the cause of the error and reenter the 
command line. Ensure that you are correcting the right file or file version. 
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Appendix A 



Command Formats 



A. 1 Introduction to Command Formats 

This appendix presents a summary of the commands and switches used by the RSX-llM-PLUS 
utilities described in this manual. Each section number of the appendix corresponds to the 
chapter discussing that utility. For example. Chapter 12 and Section A.12 both deal with PIP. 

Commands and switches are presented alphabetically within the sections of this appendix, 
regardless of their presentation in the various chapters. 

A.2 BAD 

The format for executing BAD is shown next. 

Format 

ddnn:[/switch[. . .]] 

Parameters 

ddnn: 

Specifies a physical device. 
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switch 

Specifies one of the following switches: 

/ALO:volume label Prompts you for blocks to be allocated to BADBLK.SYS and entered 
in the bad block descriptor file. 

/LI Lists bad blocks as they are located. 

/MAN Prompts you for additional bad blocks, which are entered in the 

bad block descriptor file. 

/OVR Creates the bad block descriptor file on a last-track device. 

/PAT=m:n Specifies the doubleword data pattern used to locate bad blocks. 

/RETRY Recovers soft errors. 

/UPD Reads the bad block descriptor file and prompts for input. 

A.3 BRU 

The command format for BRU is shown next. 

Format 

/qualifier[...] indevice[,...][filespec[,...]] outdevice[,...] 

Parameters 

Indevice 

Specifies the physical device (or devices) from which data is transferred. 

fliespec 

Indicates the file specification used to select files to be backed up or restored. 

outdevice 

Specifies the output device to which data is transferred. 
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qualifier 

Specifies one of the following qualifiers: 

/APPEND 



BACKUP_SET:name 



/BAD 
/BUFFERS:n 



AUTOMATIC 

MANUAL 

OVERRIDE 



/COMPARE 



/CREATED: < 



/DENSITY: 



BEFORE:dd-mmm-j^ 
BEFORE:hh:mm:ss 
BEFORE(dd-mmm-yy hh:mm:ss) 
AFTER:dd-mmm-yy 
AFTER:hh:mm:ss 
AFTER:(dd-mmm-j7y hh:mm:ss) 

800 1 
1600 \ 
6250 J 



/DIRECTORY 



/DISPLAY 



/ERRORS:n 



/EXCLUDE 



Appends backup set from the input 
disk volume to the last backup set 
on the output tape (or on the output 
disk if you are using the /IMAGE 
qualifier). 

Specifies the name of the backup 
set. 

Speccifies the locations of bad 
blocks on the volume. The default 
option is :AUTOMATIC. 

Specifies the default number of di- 
rectory File Control Blocks (FCBs) 
per volume kept by the Ancillary 
Control Processor (ACP). 

Specifies that the data on the output 
volume should be compared to the 
data on the input volume and any 
differences reported. 

Directs BRU to backup or restore 
files created before or after a speci- 
fied date and/or time. 



Specifies the data density at wrhich 
BRU writes to tape. 

Displays information (such as backup 
set names, file names, and volume 
number) for a specified volume. 

Displays at your terminal the direc- 
tory and file name of each file as 
the header of that file is transferred 
by BRU. 

Terminates the restore operation af- 
ter the specified number of nonfatal 
tape-read errors is reached. The de- 
fault is 25io errors. 

Excludes from a backup or restore 
operation all files specified on the 
command line. 
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/EXTEND:n 



/HEADERS:n 



/IDENTinCATION 

/■^^^ { Sre } 
/initialize 

/INVOLUMErname 

/LENGTH:n 

/MAXIMUM:n 

/MOUNTED 
/NEW_VERSION 



/NOINITIAUZE 
/NOPRESERVE 



Specifies the default number of 
blocks by which a file is extended 
when that file has exhausted its al- 
located space. 

Specifies the number of file headers 
to allocate initially to the index file. 

Directs BRU to identify itself by 
displapng its version. 

Specifies that you want to do a 
multiple disk-to-disk backup (SAVE) 
or restore (RESTORE) operation. 

Directs BRU to initialize the output 
disk during a tape-to-disk or disk- 
to-disk operation. 

Specifies the volume label of the 
input disk. 

Specifies the length of the output 
tape in decimal feet. 

Specifies the maximum number of 
files that can be placed on a volume 
as determined by the number of file 
headers in the volume's index file. 

Allows you to back up files from a 
disk that is mounted as a Files-11 
volume. 

Directs BRU to resolve file specifi- 
cation conflicts that occur during re- 
store operations and during backups 
to a mounted disk by creating a new 
version of the file. 

Specifies that you do not want to 
initialize the output disk because it 
is already in Files-11 format. 

Specifies that you do not want to 
preserve file IDs. 
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/NOSUPERSEDE 



/OUTVOLUME:name 



/POSITION: 



BEGINNING 
MIDDLE 
END 
BLOCK:n 



Specifies that when file specifica- 
tions on the mounted output disk 
are identical to those on the input 
volume, the file on the input vol- 
ume is not transferred. That is, the 
file on the output disk is not super- 
seded by the file on the input vol- 
ume. The /NOSUPERSEDE quali- 
fier is the default. 

Specifies the volume label of the 
output disk. The label can be up 
to 12io characters long. 

Specifies the location of the index 
file on the output disk volume being 
initialized. 



/PROTECTION: < 



SYSTEM:value 
OWNERrvalue 
GROUP:value 
WORLD:value 



/REVISED: 



/REWIND 



BEFORE:dd-minm-yy 
BEFORE:hh:mm:ss 
BEFORE:(dd-mmm-yy hh:mm:ss) 
AFTER:dd-mmm-yy 
AFTER:hh:mm:ss 
AFTER:(dd-mmm-3^ hh:mm:ss) 



1 



/SUPERSEDE 



/TAPE_LABEL:label 



Specifies the default protection sta- 
tus for all files created on the out- 
put volume being initialized. The 
protection value can be any combi- 
nation of the following: R (read), W 
(write), E (extend), or D (delete). 

Directs BRU to back up or restore 
files revised or created before, or 
after, a specified date and/or time. 



Rewinds the first tape of a tape set 
before executing a backup or restore 
operation. 

Specifies that when file specifica- 
tions on the mounted input volume 
are identical to file specifications on 
the input volume, the file on the 
output volume is deleted and re- 
placed with the file from the in- 
put volume. The default is the 
/NOSUPERSEDE qualifier. 

Specifies the 6-character volume 
identifier on the ANSI label to be 
placed on a tape during a backup 
operation or to be compared writh 
the label on the tape for append 
and restore operations. 
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/UFD 



/VERIFY 



/WINDOWS:n 



Directs BRU to create directories (if 
they do not already exist) on a 
mounted output volume, and then 
to copy the files from the same 
directories on the input volume into 
the created directories. 

Verifies that the output volume was 
written correctly by comparing the 
input volume to the output volume 
and reporting any differences. 

Specifies the default number of 
mapping pointers to be allocated for 
file windows when initializing an 
output disk. The default number 
of mapping pointers is the same for 
the input disk. 



A.4 CMP 

The format of the CMP command line is shown next. 

Format 

[outfile[/switch[...]]=]infilel,infile2 

Parameters 

outfile 

Indicates the file specification for the output file. 



infllel 



Specifies the file specification for the input file to be compared to infile2. 



inflle2 



Specifies the file specification for the output file to be compared to infilel. 
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switch 

Spedfies one of the following switches applied to the output file specification: 

/BL Spedfies that blank lines in both files be included in compare processing. If the 

[/-BL] /-BL switch is specified, blank lines are not included in compare processing. 

The /-BL switch is the default. 

/CB Spedfies that CMP list infile2 with change bars, in the form of exclamation 

[/-CB] marks (!), to denote which lines do not have a corresponding line in infileL 

The /-CB switch is the default. 

[/CO] Spedfies that CMP include comments (that is, text preceded by a semicolon 

/-CO (;)) m compare processing. The /CO switch is the default. 

[/DI] Specifies that CMP list the differences between the two files (rather than 

/-DI marking the lines in infile2). The /DI switch is the default. 

/FF Specifies that CMP include records consisting of a single form-feed character 

[/-FF] in compare processing. The /-FF switch is the default. 

/LI:n Specifies that a number of lines must be identical before CMP recognizes a 

[/LI:3] match. The /LI:3 switch is the defauh. 

[/LN] Spedfies that lines in the output file be preceded by their line number. Line 

/-LN numbers are incremented by one for each record read, including blank lines. 

The /LN switch is the default. 

[/MB] Specifies that CMP include all blank and tab characters in a line in compare 

/-MB processing. If you specify the /-MB switch, CMP interprets any sequence of 

blank and/or tab characters as a single blank character. However, all spaces 
and tabs are printed in the output listing. The /MB switch is the default. 

/SL[:au] Directs CMP to generate an output file suitable for use as SLP command input. 

[/-SL] When you specify /SL, CMP generates the SLP command input necessary to 

make infilel identical to infile2. If a 1- to 8-character alphanumeric symbol is 
included in the /SL switch (:au), an audit trail is specified for SLP input. The 
/-SL switch is the default. 

/SP[:n] Spedfies that the output file be spooled on the line printer. You can optionally 

[/-SP] spedfy the number (in octal or dedmal) of files to be spooled. The /-SP switch 

is the default. 

[/TB] Specifies that CMP include all trailing blanks on a line in compare processing. 

/-TB If you specify the /-TB switch, CMP ignores all blanks following the last 

nonblank character on a line. When you spedfy the /-CO and the /-TB 
switches together, blanks that precede a semicolon (;) are considered trailing 
blanks and are ignored. The /TB switch is the default. 

/VB:nnn Specifies an octal character code for the character you want to use as a change 

[/VB:041] bar. You use this switch with the /CB switch. The value specifies the octal 

character code. For example, you can specify /VB:174 for a vertical bar (if 

your printer is capable of printing the vertical bar character). The /VB:041 

switch (for the exclamation mark) is the default. 
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A.5 DMP 

The DMP command line format is shown next. 
Format 

[outfile][/switch[. ..]][=inspec][/switch[. . .]] 

Parameters 

outfile 

Specifies the output file specification. 

inspec 

Specifies the input device and file, or the input device only. 

switch 

Specifies one of the following DMP switches: 

/AS Specifies that data be dumped one byte at a time in ASCII mode. 

/BA:n:m Specifies a 2-word base block address, where n is the high-order base 

block address and m is the low-order base block address. 

/BL:n:m Specifies the range of blocks to be dumped, where n is the first block 

and m is the last block. 

/BY Specifies that the data be dumped in octal byte format. 

/DC Specifies that the data be dumped in decimal word format. 

/DENS- ( ^^^ \ Specifies the density of an input magnetic tape when DMP is in device 
■ I 1600 / mode. 

/FI:n:sequence Specifies in file mode that the file number be used instead of the file 

name as a file specification for input. 

/HD[:F] Specifies that the file header as well as the specified or implied portion 

/HD:U of the file be dumped. The /HD:F switch is the default, and it causes 

a Files-11 formatted dump of the header. The /HD:U switch causes 

an unformatted octal dump. 

/HF Specifies the format for data blocks that have the Files-11 header 

structure. Other blocks are output as a data dump in the format 
selected by switches such as /AS and /BY in default octal words. 

/HX Specifies that data be dumped in hexadecimal byte format. 

/ID Causes the current version of DMP to be displayed. 

/LB Requests logical block information for a file and displays the starting 

block number and a contiguous or noncontiguous indication for the 
file. 

/LC Specifies that the data should be dumped in lowercase characters. This 

switch can be used only if the output device has lowercase capability. 
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/LIM:n:m Specifies the range of bytes n to m of each record or block to be 

dumped. 

/LVV Specifies that data be dumped in hexadecimal doubleword format. 

/MD[:n] Specifies a memory dump and allows control of line numbers. 

/OCT Specifies that the data should be dumped in octal format in addition 

to the other formats specified. 

/RC Specifies that data should be dumped one record at a time. 

/RW Issues a rewind command to the tape driver before referencing a 

specified tape. The /RW switch may be specified at any time to 
re-position a tape at beginning-of-tape (BOT). 

/R5 Specifies that data be dumped in Radix-50-format words. 

/SB:n Specifies the number of blocks DMP spaces forward ( n ) or backward 

/SB:-n (-n) on tape. 

/SF:n Specifies the number of end-of-file (EOF) marks DMP spaces forward 

/SF:-n (n) or backward (-n) on a tape. 

/SP Spools the dump output file to the line printer. 

/WD Specifies that data be dumped in hexadecimal word format. 

A.6 DSC 

The DSC command line format is shown next. 

Format 

outdev[,...][filelabell][/switch[...]]=indev[,...][filelabel2][/switch[...]] 

Parameters 
outdev 

Specifies the physical volume (or volumes) to which data is copied. 

flielabell 

Specifies the output disk's Volume ID, the tape file, or the tape set that DSC creates in a 
file transfer. 

indev 

Specifies the physical volume (or volumes) from which data is copied. 

fllelabel2 

Specifies the DSC-created tape file that is being transferred to disk or compared. 
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switch 

Specifies 

/AP 



/BAD= 



/BL=n 
/BL:n 

/CMP 

/DENS= 

/DENS: 

/RW 
/VE 



one of the following switches: 

Appends a DSC file to the first volume of a tape set that 
already contains a DSC file. 

MAN ^ Allows manual entry of bad block locations; it can supple- 

NOAUTO ment, override, or ignore the disk's own bad block file. 

MANrNOAUTO 

OVR 

MAN:OVR 

Sets the number of 256-word blocks DSC can include in 
each of its two buffers. 

Compares input and output volumes for differences. 

Overrides the DSC default storage density for magnetic tapes 



r 800 \ 
I 1600 J 



of 800 bpi. 



Rewinds all magnetic tapes before DSC executes the current 
command. 

Copies data from the input volume and compares it with 
data in the output volume. 



A.7 EDI 

The commands for the EDI editor are shown next. 

Commands 

A string 

Causes the specified string to be appended to the current line. 

ALTMODE l<ey 

Causes the system to print the previous line in the block in block mode only. That line 
becomes the current line. 

AP string 

Causes the specified string to be appended to the current line, and displays the new current 
line. 

B 

Sets the current line pointer to the beginning of the file in line-by-line mode or to the 
beginning of the block buffer in block mode. 

BL [ON] 
BLOFF 

Switches text between block mode and line-by-line mode. 
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BO 

Moves the current line pointer to the beginning of the last line of the current block in block 
mode or to the beginning of the last line of the file in line-by-line mode. 

[n]C /string l/string2[/] 

Searches for and replaces stringl with string2 the number of times specified in the current 
line. 

CC [character] 

Changes the current concatenation character to the specified character. The default is the 
ampersand character (&). 

CD [fllespec] 

Transfers all remaining lines in the block buffer and then the input file into the output file, 
closes both files, and then deletes the input file. If filespec is specified, the output file is 
renamed. 

CL [fllespec] 

Transfers aU remaining lines in the block buffer and then the input file into the output file 
and closes both files If filespec is specified, the output file is renamed. 

CLOSES 

Closes the secondary input file. 

CTRL/Z 

Closes files and terminates the editing session. 



D[n] 
D-n 



Deletes the current line and next n-1 lines if n is positive; deletes n lines preceding the 
current line, but not the current line, if n is negative. The Delete [-n] command is valid 
only in block mode. 



DP [n] 
DP -n 

Performs the same function as the Delete command except that the new current line is 
displayed. 

E 

Performs the same function as the BOttom command. 

ED [filespec] 

Transfers all remaining lines in the block buffer and then the input file into the output 
file, closes both files, deletes the input file, and terminates the editing session. If a file 
specification is specified, the output file is renamed to that file name. 

ERASE [n] 

Erases the current line in line-by-line mode, or erases the current block buffer and the next 
n-1 blocks in block mode. 
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ESCAPE key 

Prints the previous line in the block (block mode only) making it the new current line. 
Pressing the ESACPE key in input mode terminates the line of input and, if entered as the 
first character in the line, exits from input mode. 

EX [fliespec] 

Transfers all remaining lines in the block buffer and input file (in that order) into the output 
files, closes the files, and terminates the editing session. If a file specification is specified, 
the output file is renamed to that file name. 

[n]F [string] 

Searches the block buffer or input file for a string. If n is specified, the nth occurrence of 
the string is found. 

FF 

Inserts a form feed into the text to delimit a pages. 

FIL fliespec 

Transfers lines from the input file to both the output file and the specified file in line-by-line 
mode only. 

I [string] 

Inserts a string immediately following the current line. If a string is not specified, EDI enters 
input mode. 

KILL 

Closes the input file and deletes the output file. 

[n]L [string] 

Searches the block buffer or input file for the nth occurrence of a string or, if a string is not 
specified, considers the current line a match and positions the line pointer there. 

[n]LC /string l/string2[/] 

Changes all occurrences of stringl in current line and the next n-1 lines to string2. If string2 
is not specified, all occurrences of stringl are deleted. 

LI 

Prints on your terminal all remaining lines in the block buffer or input file, beginning with 
the current line. 

LP 

Lists the remaining lines in the block buffer or input file on the pseudo device CL, beginning 
with the current line. 

[n]Mx [a] 

Executes n times the macro x, while passing it an optional numeric argument a. 

MACRO X deflnltlon 

Defines macro number x. The value of x can be 1, 2, or 3. 
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MC 

Retrieves up to three macro definitions previously stored in the latest version of the file 
MCALL;n. 

[n] <deflnition> 

Defines and executes, in one step, a macro n times. The macro definition is copied into the 
macro 1 storage area. 

N[n] 
N -n 

Moves the current line pointer backward (-n) or forward (n) a number of lines from the 

current position. 

NP[n] 
NP-n 

Moves the current line pointer backward (-n) or forward (n) a number of lines from the 
current position and prints the new current line. 

0[n] 

Deletes the current line and the next n-1 lines, enters input mode, and inserts your typed 
text into the file until you enter a RETURN key as the only character in an input line. 

OP filespec 

Opens the specified secondary input file. 

OU [ON] or 
OUOFF 

Continues or discontinues the transfer of text to the output file in line-by-line mode only. 

P[n] 

Prints the current line and the next n-1 lines on your terminal. The last line printed becomes 
the new current line. 

PA /string l/string2[/] 

Changes all occurrences of stringl to string2. Same as the LC command, except that all 
lines in the remainder of the block buffer or input file are searched for stringl. Wherever 
found, stringl is replaced vdth string2. 

PAG n 

Enters block mode, if not already in block mode, and reads page n into the block buffer. 

[n]PF string 

Searches successive block buffers until the nth occurrence of the string is found, and copies 
the contents of the block buffer and the blocks between the current block and the block in 
which the nth occurrence of the string is located in the output file. 

[n]PL string 

Searches successive block buffers for the nth occurrence of the string and writes the text 
from the current block buffer into the output file. 
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R [String] 

Replaces the current line with the string. If a string is not specified, the current line is 
deleted. 

REA [n] 

Reads the next n blocks of text into the block buffer. If a block is already in the buffer, the 
new block or blocks are appended to it. 

REN [n] 

Writes the current block buffer into the output file and reads a new block from the input 
file n times in block mode only. 

RETURN key 

Prints the next line in the file or block buffer and makes it the current line. In input mode, 
pressing the RETURN key causes EDI to change to edit mode. 

SA [n] [fllespec] 

Saves the current line and the next n-1 lines in the file specified and creates a new version if 
the file already exists. If file specification is not given, the lines are saved in file SAVE.TMP. 

SC /string l/string2[/] 

Searches for string! in the input file or block buffer and replaces it with string2. 

SiZE n 

Specifies the maximum number of lines to be read into the block buffer on a single REA or 
REN command. 

SP 

Selects or reestablishes the primary file for input. 

SS 

Selects the secondary file as the input file. 

T 

Moves the current line pointer to the top of the current block or file. 

TA [ON] 
TAOFF 

Turns automatic tabbing on or off. 

TOF 

Copies the input file into the ouput file, closes both files, and opens the latest version of the 
output file as the input file. If TOF is entered while in line-by-line mode, EDI switches to 
block mode after saving the edited data. The first block is then read into the block buffer. 

TY[n] 

Prints the next n lines. In line-by-line mode, the last line printed becomes the new current 
line. In block mode, the current line pointer does not change unless end-of-buffer (EOB) is 
reached. 
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UC [ON] 
UC OFF 

Allows you to enter lowercase letters from a terminal and have them converted to uppercase 

letters. 

UNS [fliespec] 

Retrieves all the lines in a specified file and copies them after the current line. If no file 
specification is given, the default file SAVE.TMP is used. 

V [ON] 

V OFF 

Determines whether the lines specified by the L and C commands are verified or displayed. 

W 

Writes the entire contents of the current block buffer to the output file and then erases the 
block buffer in block mode only. 

A.8 FLX 

The FLX command line format is shown next. 

Format 

[ddnn:[[directory]]/switch[. . .]=]infilel [,. . .]/switch[. . .] 

Parameters 

ddnn 

Specifies the device for the FLX output. 

directory 

Specifies the directory on the output device. If directory is not given, the default directory 
is used. Do not specify a directory if the output device is in RT-11 format. 

Inflle 

Specifies the file specification for input. 
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Compress Switch Format 

outfile/CO:size:ept:mnt=infile 

Parameters 

outflle 

Specifies the file specification that is to become the compressed version of the input file. 

size 

Specifies the size of the new library file in 256]o-word blocks. The size of the old library 
file is the default size. 

ept 

Specifies the number of entry point table (EPT) entries to allocate. The number of EPTs in 
the old library file is the default value. The maximum number of entries is 4096 lo. 

mnt 

Specifies the number of module name table (MNT) entries to allocate. The number of MNTs 
in the old library file is the default value. The maximum number of entries is 4096io. 

inflle 

Specifies the library file specification to be compressed. 

Create Switcti Format 

outfile/CR:size:ept:mnt:libtype:infiletype 

Parameters 

outfiie 

Specifies the library file specification being created. 

size 

Specifies the size of the new library file in disk (256io-word) blocks. The default size is 
lOOio-blocks. 

ept 

Specifies the number of entry point table (EPT) entries to allocate. The default value is 
512io for object libraries. The maximum number of entries is 4096io. 

mnt 

Specifies the number of module name table (MNT) entries to allocate. The default value is 
256io. The maximum number of entries is 4096io. 

ilbtype 

Specifies the type of library to be created. Acceptable values are OBJ for object libraries, 
MAC for macro libraries, and UNI for universal libraries. The default is the last value 
specified or implied with the Default switch (/DF) (see Section 10.3.2.4), or OBJ if the /DF 
switch has not been specified. 
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inflletype 

Specifies the default input file type for the created universal library. If this value is not 
specified, the default input file type for universal libraries is UNI. This value is not defined 
for object or macro libraries. 

Delete Switch Format 

outfile/DE:module[...] 

Parameters 

outflle 

Specifies the library file specification. 

module 

Specifies the name or names of the module or modules to be deleted. 

Default Switch! Formats 
outfile/DF:filetype 

or 

/DF:filetype 

Parameters 

outflle 

Specifies the library file specification. 

flietype 

Specifies the default library file type: OBJ for object library files, MAC for macro library 
files, and UNI for universal library files. 

Delete Global Switcti Format 

outfile/DG:global[...] 

Parameters 

outflle 

Specifies the library file specification. 

global 

Specifies the name or names of the entry point or points to be deleted. Up to 15io entry 
points may be deleted with one command line. 

Entry Point Switchi Formats 

outfile/EP=infile[,...] 

or 

outfile=infile/EP[,...] 
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Parameters 

outflie 

Specifies the output file specification. 

inflle 

Specifies the input file specification. 

Extract Switch Format 

outfile=infile/EX[:modulename[...]] 

Parameters 

outflie 

Specifies the file specification into which extracted modules are to be stored. If the input 
modules are object modules, the default file type for this file is OBJ. If the input modules 
are macro modules, the default file type is MAC. If the library is a universal library, the 
outfile retains the infile type of the module extracted. (However, you are allowed to extract 
only one universal library module at a time.) 

infile 

Specifies the library file specification from which the modules are to be extracted. The 
default file type for this file is ULB, OLE, or MLB, depending on the current default library 
type. 

modulenome 

Specifies the name or names of the module or modules to be extracted from the library. 

Insert Switch Format for Object and IVIacro Libraries 

outfile/IN=infile[,...] 

Parameters 

outflie 

Specifies the library file specification into which the input modules are to be inserted. The 
default file type depends on the current default (see Section 10.3.2.4). It is OLE if the 
current default is object libraries, MLE if the current default is macro libraries. 

Inflle 

Specifies the input file specification containing the modules to be inserted into the library 
file. The default file type is OBJ if the outfile is an object library and MAC if the outfile is 
a macro library. 

insert Switch Format for Universal Libraries 

outfile=infile/IN:name[:op[. . .]] 
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Parameters 

outfile 

Specifies the universal library file specification into which the infile is to be inserted. 

infile 

Specifies the input file specification to be inserted into the outfile. The default for the file 
type is the value indicated at the universal library's creation time. (See Section 10.3.2.2.) 

name 

Specifies the module name (up to six Radix-50 characters) optionally. The default is the 
first six characters of the input file name. 

op 

Specifies optional descriptive information (up to six Radix-50 characters) to be stored in 
the module header. The default is null. If only part of the information set is specified, all 
preceding colons must be supplied. 

List Switch Format 

outfile[,listfile]/switch 

Parameters 

outfile 

Specifies the library file specification whose contents are to be listed. 

Ilstfile 

Specifies the listing file specification optionally. If not specified, the listing is directed to the 
initiating terminal. 

switch 

Specifies one of the list switches (/LI, /LE, and /FU) that is used to produce a printed 
listing of the contents of a library file. The three switches allow you to select the type of 
listing desired. The functions of these switches are as follows: 

/LI Lists the names of all modules in the library file. 

/LE Lists the names of all modules in the library file and their corresponding entry points. 

/FU Lists the names of all modules in the library file and gives a full module description 
for each; that is, size, date of insertion, and module-dependent information. 

The /LI switch is the default value. 

Modify Header Switcti Format 

outfile/MH:module[:op[...]] 
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Parameters 

outfile 

Specifies an output file specification for the universal library. The file type defaults to ULB. 

module 

Specifies the name of the module whose descriptive information is to be modified. 

op 

Specifies the optional user information (up to six Radix-50 characters) to be stored in the 
module header. The default is null and indicates that the corresponding information field is 
not to be changed. Also, entering a number sign ( # ) clears the corresponding information 
field. 

Replace Switch Formats for Macro and Object Libraries 

outfile/RP=infile[,...] 

or 

outfile=infile[/RP][,...] 

Parameters 

outfile 

Specifies the macro or object library file specification. The default file type depends on the 
current default (see Section 10.3.2.4). It is OLB if the current default is object libraries or 
MLB if the current default is macro libraries. 

inflle 

Specifies the input file specification that contains replacement modules for the library file. 
The default type is OBJ if outfile is an object library or MAC if it is a macro library. 

Replace Switcti Formats for Universal Libraries 

outfile/RP:name[:op[. . .]]=infile[,. . .] 

or 

outfile=infile/RP:name[:op[.. .]][,...] 

Parameters 

outfile 

Specifies the universal library file specification. 

Infile 

Specifies the input file specification that contains replacement modules for the library file. 
The default for the file type is the value indicated at the universal library's creation time. 

name 

Specifies the module name to be replaced (up to six Radix-50 characters). The default is 
the first six characters of the infile name. 
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op 

Specifies optional descriptive information (up to six Radix-50 characters) to be stored in 
the module header. The default is null. If only part of the information set is specified, all 
preceding colons must be supplied. 

Spool Switch Formats 

outfile,listfile/SP 

or 

outfile,listfile/-SP 

Parameters 

outflle 

Specifies the library file specification. 

listfile 

Specifies the listing file specification. 

Selective Seorcti Switchi Format 

outfile=infile/SS[,...] 

Parameters 

outflle 

Specifies the library file specification. 

inflle 

Specifies the input file specification that contains modules to be searched selectively. 

Squeeze Switch formats 

outfile/SZ=infile[,...] 

or 

outfile=infile/SZ[,...] 

Parameters 

outflle 

Specifies the library file specification. 

Inflle 

Specifies the input file specification that contains modules to be squeezed during insertion 
into the library file. 



Command Formats A-23 



A.n PAT 

The PAT command line format is shown next. 

Format 

[outfile]=infile[/CS[:n]],correctfile[/CS[:n]] 

Parameters 

outfiie 

Specifies the output file specification. 

inflle 

Specifies the input file specification. 

n 

Specifies the value that PAT compares to the checksum value and returns an error message 
if the two values are different. 

A. 12 PIP 

The PIP command line formats are shown next. 

Append Switcti Format 

outfile=infile[,...]/AP[/FO] 

Parameters 

outflle 

Specifies the output file specification. 

inflle 

Specifies the input file specification. If the file name, file type, and version are not specified, 
then *.*;• is the default. 

Block Size Swltcti Format 
outfile/BS:n=infile 

Parameters 

outflle 

Specifies the output file specification. 

n 

Specifies the number of bytes in a block in octal or decimal. 

inflle 

Specifies the input file specification. 
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Creation Date Swltcti Format 

outffle/CD=infile[,...] 

or 

outfile=inme/CD[,...] 

Parameters 

outfiie 

Specifies the output file specification. 

infile 

Specifies the input file specification. 

Default Date Switch) Format 

/DD:startdate:enddate 

Parameters 
startdate 

Specifies the beginning date of the time period in the form dd-mm-yy. It may be unlimited 
by using the wildcard character { * ). 

enddate 

Specifies the ending date of the time period in the form dd-mm-yy. It may be unlimited by 
using the wildcard character ( * ). 

Delete Swltcti Format 

infile[,...]/DE[/LD] 

Parameter 

infile 

Specifies the input file specification. 

Default Switcti Format 

ddnn:[directory]/DF 

or 

ddnn:/DF 

or 

[directory]/DF 

or 

/DF 
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Parameters 

ddnn 

Specifies the new default device to be applied to subsequent PIP command lines. 

directory 

Specifies the new default directory to be applied to subsequent PIP command lines. 

End-of-File Switch Format 

infile/EOF[:block:byte][,...] 

Parameters 

Inflle 

Specifies the input file specification. 

The file specification must be issued. There is no default. 

blocic 

Specifies the block number where the EOF pointer is to be placed. The block number can 
be octal or decimal. 

byte 

Specifies the byte location of EOF is the first unused byte of the specified block. The byte 
number can be octal or decimal. The maximum value for byte is 7778. 

Enter Switch Format 

outfile=infile[,...]/EN[/NV] 

Parameters 

outflle 

Specifies the file specification for the new directory entry. 

inflle 

Specifies the input file specification. The default input file specification is *.*;*. 

File Exclusion Switch Format 
filespec/EX 

Parameter 

fliespec 

Specifies the file specification. The file name and/or the file type and/or the version number 
can be a wildcard, but all three fields cannot be wildcards. Also, you cannot specify devices 
or directories. 

File Identification Switch Format 

outfile=/FI:filenum:seqnum 
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Parameters 

fllenum 

Specifies the file number. 

seqnum 

Specifies the sequence number of the file. 

Free Switch Format 

[ddnn:]/FR 

Parameter 

ddnn 

Specifies the desired volume. If you do not specify a device, PIP defaults to SYO. 

Identify Switch Format 

/ID 

List Switch Format 

pistfile=]infile[,...]/LI[/subswitch] 

Parameters 

listflie 

Specifies the file specification to be listed. 

If listfile is not specified, it defaults to TI. 

inflle 

Specifies the input file specification. 

The default for infile is *.*;*. 

subswitch 

Specifies the alternate mode subsvdtch of the /LI switch as follows: 

/BR Specifies the brief form of directory listing. This subswitch lists only the file 

name, file type, and version. 

/FU[:n] Specifies the full directory format. If specified, n is the number of characters 

per line. If not specified, the number defaults to the buffer size of the output 
device. 

/TB This subswdtch specifies the total number of blocks used for a directory and 

outputs the summary line. 

Merge Switch Format 

outfile=infile[,...][[/ME][/subswitch]] 
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Parameters 

outflie 

Specifies the output file. 

infile 

Specifies the input file. 

subswitch 

Specifies one of the following /ME subswitches as follows: 

/BL:n Specifies the number of blocks to be allocated initially to the output file. 

/CO Specifies that the output file be contiguous. The /-CO switch specifies that 

the ouput file does not have to be contiguous. 

/FO Specifies that the owner of the output file be the same as the output 

directory. 

/NV Forces the output version number of the file being copied to become one 

greater than the latest version of the file already in the output directory. 

/SU Allows you to copy one or more input files to a file whose file name, file 

type, and version may already exist in a directory. 

No Message Switch Format 

infile[,...][switch]/NM 

Parameters 

inflie 

Specifies the input file specification. 

switch 

Specifies any combination of appropriate switches and subswitches. 

Protect Switch Format 

infile/PR[:n][/SY[:RWED]][/OW[:RWED]][/GR[:RWED]][/WO[:RWED]][/FO] 

Parameters 

infile 

Specifies the file specification whose protection is being changed. 

The file specification must be issued. There is no default. 
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/SY, /OW, /GR, and /WO 

Spedfies the subswitches that set the protection level for a file. The subswitches are 
identified as follows: 



Subswitch Description 



/SY 


System 


/OW 


Owner 


/GR 


Group 


/WO 


World 



n 

Spedfies a value that is the odal representation of the protection to be assigned to the 
file. This octal number is taken as the new protection word. (See the RSX-UM-PLUS 
Mini-Reference for the list of octal codes.) 

Purge Switch Format 

infile[,...]/PU[:n][/LD] 

Parameters 

infiie 

Specifies the file spedfication to be deleted. 

Note that a version number is not needed. If specified, it is ignored. 

n 

Spedfies a range of obsolete versions of a file. If the latest version of the file is m, then 
all existing versions less than or equal to m-n are deleted. If you omit the value n, PIP 
defaults to 1, and all but the latest version of the file are deleted. If n is greater than the 
number of versions of the spedfied files, no files are deleted. 

Rename Switch Format 

outfile=infile[,. . .]/RE[/NV] 

Parameters 
outflle 

Specifies the file spedfication to be given to the new file. 

inflle 

Specifies the file specification to be renamed. 

/NV 

Spedfies the New Version subswitch. The /NV subswitch forces the version number of the 
renamed file to a number one greater than the latest version for the file. 
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Remove Switch Format 

mfile[,...]/RM 

Parameter 

inflle 

Specifies the file specification for the directory file entry to be removed. 

The file specification must be issued. There is no default. 

Rewind Switcti Formats 

outfile/RW=infile 

or 

outfile=infile/RW 

Parameters 

outflie 

Specifies the output file specification. 

inflle 

Specifies the input file specification. 

Span Bloci(s Switcti Format 

ddnn:outfile/SB=mmnn:infile 

Parameters 

ddnn 

Specifies the output disk volume. 

mmnn 

Specifies the input tape volume. 

outflie 

Specifies the disk output file specification. 

inflle 

Specifies the magnetic tape input file specification. 

Selective Delete Switcti Format 

infile[,...]/SD 

Parameter 

inflle 

Specifies the input file specification. 

The file specification must be issued. There is no default. 
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Spool Switch Format 

infile[,...]/SP[:n] 

Parameters 

infile 

Specifies the file specification to be spooled for printing. 

n 

Specifies the number of copies you want spooled. 

Stiared Reading Switcti Format 

outfile=infile/SR 

Parameters 

outflle 

Specifies the output file specification. 

infile 

Specifies the input file specification. 

Today Switch Format 

/TD 

Truncate Switch Format 

infile[,...]/TR 

Parameter 

infile 

Specifies the input file specification. 

The file specification must be issued. There is no default. 

User File Directory Switch Format 

outfile/UF[/FO]=infile[,...] 

Parameters 

outflle 

Specifies the file specification for the output file. 

infile 

Specifies the file specification for the input file. 

Unlock Switch Format 

infile[,..]/UN 
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Parameter 

inflle 

Specifies the file specification for the file to be unlocked. 

Update Switch Format 
outfile=infile[,...]/UP[/FO] 

Parameters 

outflle 

Specifies the file specification for the file to be rewritten. 

inflle 

Specifies the file specification for the file to be copied into the file that is being rewritten. 

An unspecified file name, file type, and version default to *.*;*. 

A. 13 SLP 

The format of the SLP command line is shown next. 

Format 

outfile[/switch][,listfile][/switch]=[primary_input_device:[/switch]] 

Parameters 

oufile 

Specifies the output file specification 

llstflle 

Specifies the file specification for the listing file. 

prlmary_lnput_device 

Specifies that input for the file being created is coming from this device. 
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switch 

Specifies one of the following SLP switches: 

[/AU:position:length] Enables or disables the auciit trail, which indicates the changes made 
during the most recent editing session. If the audit trail is to be 

/-AU enabled, you can specify the beginning field (position) and the length 

of the field. 

[/BF] Positions the audit trail by inserting spaces instead of tabs at the end 

/-BF of text information. 

/CM[:n] Deletes the audit trails and any trailing spaces or tabs, and truncates 

the text at the specified horizontal position n. 

/CS[:n] Calculates the checksum value for the edit commands. 

/DB Enables or disables the double-spaced format in the listing file. 

[/-DB] 

/NS Does not sequence lines in the output file. New lines are indicated 

by the audit trail (if specified). This switch overrides the /RS and 
/SQ switches. 

/RS Resequences the lines in the output file so that the line numbers are 

incremented for each line written to the output file. 

[/SP] Enables or disables the spooling of listing files to a line printer. 

/-SP 

/SQ Sequences the lines in the output file so that the numbers reflect the 

line numbers of the original input file. 

/TR Specifies that a diagnostic error message occurs when lines are 

truncated by the audit trail. 

A. 14 VFY 

The format of the VFY command line is shown next. 

Format 

[listfile,scratchdev=][indev]/switch 

Parameters 

listfiie 

Specifies the output file specification. 

scratchdev 

Specifies the device in the form ddnn on which the scratch file produced by VFY is to be 
vmtten. 

indev 

Specifies the volume to be verified in the form ddnn. 
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switch 

Specifies one of the VFV switches as follows: 

/DE Resets the marked-for-deletion indicators. 

/DV Validates directories against the files they list. 

/FR Prints out the available space on a volume. 

/HD Deletes bad file headers on a volume. The All subswitch (/AL) allows the /HD 

switch to delete bad file headers without prompting the user. 

/ID Identifies the VFY version. This switch may be specified on a command line by 

itself at any time. 

/LI Lists the index file by file ID. 

/LO Scans the file structure looking for files that are not in any directory. 

/RC Checks the volume to see if every block of every file can be read. 

/RE Recovers blocks that appear to be allocated but are not contained in a file. 

/UP Allocates blocks that appear to be available but are actually allocated to a file. 

A.15ZAP 

The general ZAP command line format is shown next. 

Format 

filespec/switch[. . .] 

Parameters 

fliespec 

Specifies the file you want changed. Refer to Chapter 1 for detailed descriptions of the 
parameters for file specifications. 

switch 

Specifies one of the following ZAP switches: 

/AB Specifies the Absolute Mode switch 

/LI Specifies the List switch which displays the overlay segment table for an overlaid 

task image file. 

/RO Specifies read-only mode. 

A. 1 5. 1 ZAP Open and Close Commands 

ZAP open and close commands allow you to open locations in a file, modify those locations, 
and dose the locations. 
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Commands 

/ (slash) 

Opens a location, displays its contents in octal, and stores the contents of the location in 
the Quantity Register ( Q ). If the location is odd, it is opened as a byte. 

" (quotation marks) 

Opens a location, displays the contents of the location as two ASCII characters, and stores 
the contents of the location in the Quantity Register ( Q ). 

% (percent sign) 

Opens a location, displays the contents of the location in Radix-50 format, and stores the 
contents of the location in the Quantity Register (Q). 

\ (backslash) 

Opens a location as a byte, displays the contents of the location in octal, and stores the 
contents of the location in the Quantity Register (Q). 

' (apostrophe) 

Opens a location, displays the contents as one ASCII character, and stores the contents of 
the location in the Quantity Register ( Q ). 

[ret] (RETURN key) 

Closes the current location as modified and opens the next sequential location if no other 
values or commands are on the command line. ZAP commands take effect only after you 
press the RETURN key. 

' or t (circumflex or up arrow) 

Closes the currentiy open location as modified and opens the preceding location. 

_ (underscore) 

Closes the currently open location as modified, uses the contents of the location as an offset 
from the current location, and opens the new location. 

@) (at sign) 

Closes the currentiy open location as modified, uses the contents of the location as an 
absolute address, and opens that location. 

> (right angle bracket) 

Closes the currently open location as modified, interprets the low-order byte of the contents 
of the location as the relative branch offset, and opens the target location of the branch. 

< (left angle bracket) 

Closes the currentiy open location as modified, returns to the location from which the last 
series of underscore (_), at sign (@), and/or right angle bracket (> ) commands began, 
and opens the next sequential location. 
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A. 15.2 ZAP General-Purpose Commands 

ZAP general-purpose commands are used to calculate displacements, verify location contents, 
and exit from ZAP. 

Commands 

X 

Exits from ZAP; returns control to the Command Line Interpreter (CLI). 

K 

Calculates the offset in bytes between an address and the value contained in a Relocation 
Register, displays the offset value, and stores it in the Quantity Register ( Q ). 

O 

Displays the jump and branch displacements from the current location to a target location. 

Displays in octal the value of the expression to the left of the equal sign. 

V 

Verifies the contents of the current location. 

R 

Sets the value of a Relocation Register. 
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Appendix B 



The Cross-Reference Processor (CRF) 

The Cross-Reference Processor (CRF) is an independent task that produces cross-reference 
listings for the MACRO-11 and Task Builder (TKB) tasks. CRF is invoked by the cross-reference 
switch in the MACRO-11 or TKB command line. Once execution is complete, CRF builds 
cross-reference listings by using the execution-time symbol tables built by those tasks. 

Two cross-reference listings are buih for the TKB, one listing the modules that reference global 
symbols during task execution and another that shows the modules contained in a given overlay 
segment. 

Four cross-reference listings are produced for the MACRO-11 task; each shows a page and line 
number reference to a type of symbol referenced during execution of the MACRO-1 1 assembler. 

This appendix describes how CRF processes data and shows the formats of files CRF uses during 
that processing. Also, CRF error messages are listed. 

For information on how to invoke CRF in the MACRO-11 command line, refer to the PDP-11 
MACRO-11 Language Reference Manual. For information on how to invoke CRF with the TKB 
command line, refer to the RSX-llM-PLUS and Micro/RSX Task Builder Manual. 

B. 1 How CRF Processes Data 

When the /CRO switch is specified in the MACRO-11 or TKB command line, those tasks perform 
additional processing before passing control to the CRF processor. This section describes how 
cross-reference listings are generated in two phases. The first phase consists of the processing 
steps performed by MACRO-11 or TKB; the second phase consists of processing steps performed 
by CRF. Figure B-1 is an overview showing the processing steps performed in each phase, along 
with input and output files used. 
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Figure B-1: How MACRO-1 1, TKB, and CRF Generate Cross-Reference Listings 
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B.1.1 MACRO-1 1 or Task Builder Processing 

The first steps to produce cross-reference listings are performed by the MACRO-1 1 assembler or 
the Task Builder (TKB) and the /CRO switch. These tasks generate three files during execution: 
an object file (OBJ-type) or task image file (TSK-type), a listing file (LST-type or MAP-type), 
and a CRF symbol table file (CRF-type). 

The object file or task image file is directed to an appropriate device and does not affect CRF 
processing. 

The listing file consists of text information generated during the execution of the tasks, for 
example, the listing of the source code in a MACRO-1 1 program. If the output device for the 
listing file is sequential or record-oriented, as in the case of LP, a temporary listing file is created 
on SYO. 

The CRF symbol table file consists of symbol tables built during MACRO- 11 or TKB task 
execution. These tables are used by CRF to generate cross-reference listings. 

The task originating the request for cross-reference processing then sends CRF a SEND packet, 
using information in the listing file and the file name and file type specified on the command 
line. The SEND packet contains enough data to identify the symbol table file and the listing 
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file. CRF receives the packet and uses it to locate the symbol table file and listing file produced 
by MACRO-11 or TKB. 

The formats of the symbol table file and the SEND packet are shown in Figures B-2 and B-3. 

If spooling is requested with the /SP switch and the output device is a random-access device, 
the spooling flag in the SEND packet is set. CRF then passes the listing file to the print spooler 
for printing. 

B.1.2 CRF Processing 

The SEND packet contains pointers to the CRF symbol table file and the listing file. CRF uses 
the information in the listing file and the SEND packet to specify the symbol table file for 
processing (CRF-type), as follows: 

Symbol table file name - Text file name 

Symbol table file type - CRF 

Symbol table version - Contents of SEND packet word 11 

Symbol table 

device and unit - Listing file device and unit 

CRF then generates the requested cross-references and appends them to the listing file. When 
all cross-references have been generated, CRF deletes this file. 

B.2 The CRF Symbol Table File 

The CRF sjmtibol table file is a series of contiguous 5-word data records preceded by a 9-word 
header record, as shown in Figure B-2. The symbol table file is assumed to reside on the same 
device and have the same name as the input listing file, except that the file has a file type of 
CRF, as follows: 

filename. CRF 

The header record contains the name of the originating task in 2-word Radix-50 format, which 
is followed by a number value assigned by the system to identify the task. This value allows 
CRF to locate the internal tables CRF uses to format output. The next five words define the 
creation date of the symbol table file. The last word contains the flags that define the output 
format. 

Bit of the flags word controls the width of the listing. When this bit is set to zero, the listing is 
generated in 132-column format. When this bit is set to 1, the listing is generated in 80-column 
format. 

The remaining records in the symbol table file are data records. The first two words of a data 
record comprise the symbol name in Radix-50 format. The symbol value is an octal quantity 
associated with the symbol name. The second two words comprise the reference identifier, 
which is used as the cross-reference value. In the case of global symbols, this value is the 
module name in Radix-50 format. In the case of MACRO-1 1 cross-references, the value is the 
page and line number of the reference. The last word of the data record comprises the attribute 
flag byte and the format number byte. 



The Cross-Reference Processor (CRF) B-3 



The attribute flag byte contains the bits describing the attributes of the reference. These flags 
cause the special characters and abbreviations to be displayed with the reference. A number 
sign (#) means that the reference is the place where the symbol is defined. An asterisk (•) 
means that there is a destructive reference to the symbol (that is, its contents are changed). If 
there is nothing in front of the reference, it means that there is a nondestructive reference to 
the symbol (that is, its contents are read). 

The format number byte defines the format of the output. The format number is used by CRF 
to locate a set of internal tables that define the listing format associated with the entry. The 
type of cross-reference and the set of symbols associated with the flags byte is determined by 
the format number. Use of the format byte permits several types of cross-reference output to 
be generated by a single originating task. 

Figure B-2: Format of the CRF Symbol Table File 
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B.3 The CRF SEND Packet 

The CRF SEND packet is a block of data that contains control information created by TKB or 
MACRO- 11 for use by CRF. This control information enables CRF to locate the symbol table 
file and the listing or memory allocation output file. 

The SEND packet consists of 17 words, as described in Figure B-3. 

Words and 1 of the SEND packet contain the name of the sending task. Words 2 to 4 contain 
the file name of the output listing file in Radix-50 format. Word 5 contains the file type of 
the output listing file. Word 6 contains the version number of the output listing file. Words 
7 to 11 contain the directory identifier. Word 12 contains the device name of the device on 
which the output listing file resides. The first byte of word 13 is a flag byte used by CRF for 
output processing. When this bit is set to \, the output listing file is spooled off line when 
CRF completes processing. The second byte of word 13 specifies the unit on which the listing 
output file resides. Word 14 contains the symbol table file version number. Word 15 contains 
the device name of the output device. The first byte of word 16 is reserved. The second byte 
of word 16 is the unit number of the output device. 
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Figure B-3: Format of the CRF SEND Packet 
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B.4 CRF Messages 

CRF displays fatal and diagnostic error messages. Each message is preceded by one of the 
following prefixes: 



CRF — *DIAG* - name of originating task - message 
CRF -- *FATAL* - name of originating task - message 



Diagnostic errors will not terminate the CRF session and are displayed for your information. 

Fatal error messages describe a condition that caused CRF to terminate the processing of a 
command. When this occurs, CRF returns to the highest level of command input. For example. 
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if the original command is entered in response to the Monitor Console Routine (MCR) prompt, 
CRF will issue the fatal error message, exit, and prompt you with the MCR prompt, as follows: 

>utility commandline 
>CRF -- *FATAL* - message 
> 

If the command is entered in response to the utility prompt, CRF will issue a fatal error message 
and prompt you with the utility prompt, as follows: 

utllit7>coiiifflandline 

CRF ~ *FATAL* - message 

utility> 

The following error messages are output by CRF: 
CRF input file filename has lllegol format 

Explanation: This error is caused by a software error in the originating task. The symbol 
table file submitted for CRF processing contains no data. 

User Action: Submit a Software Performance Report (SPR) with the related console dialog 
and any other pertinent information. 

Failed to delete file filename 

Explanation: CRF was unable to delete the specified file for one of the following reasons: 

• CRF did not have deletion privileges for the directory under which the file resides. 

• The device was not write-enabled or ready to perform I/O. 

User Action: Initialize the device appropriately and ensure that the directory has owner- 
delete privileges. 

File filename not found 

Explanation: The file could not be located. The file was probably deleted before CRF could 
process it. 

User Action: Rerun the appropriate task to produce cross-reference output. Do not delete 
any files until CRF completes processing. 

Illegal error/severity code data 

Explanation: This error indicates a CRF malfunction; CRF has called its error message 
processor with an illegal parameter. 

User Action: Submit an SPR containing a copy of the message as printed. 
Input from unknown tasic 

Explanation: Cross-reference processing requested by the originating task is not supported 
by CRF. 

User Action: Delete the request for CRF processing and rerun the originating task. 
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I/O error on file fllenome 

Explanation: An error has been encountered while CRF was reading or writing the specified 
file. A possible hardware problem is indicated, or the device may have insufficient space to 
accommodate the CRF output file. 

User Action: Isolate the problem and take corrective action. Rerun MACRO- 11 or TKB to 
produce the cross-reference output. 

Invalid output format specified 

Explanation: This error indicates an inconsistency in the data file submitted for CRF 
processing. 

User Action: Submit an SPR with the related console dialog and any other pertinent 
information. 

No dynamic storage available 

Explanation: The CRF task requires more working storage than is available within the area 
of memory owned by the task. 

User Action: If possible, install CRF in a larger partition or with a larger increment. 

No virtual memory storage available 

Explanation: The CRF work file storage requirements exceed 65,536 words. 

User Action: No recovery is possible from this error. If possible, install the task in a larger 
partition. 

Open failure on tile filename 

Explanation: CRF was unable to open the named file for one of the following reasons: 

• The device was not ready to perform I/O. 

• The device was not write-enabled. 

• A Files- 11 device was not mounted. 

• CRF did not have extend or delete privileges for the directory under which the file 
resides. 

• The file was deleted before it could be processed by CRF. 

User Action: Isolate the problem, take appropriate corrective action, and rerun the task to 
obtain cross-reference output. 

Symbol table search stack overflow 

Explanation: This error indicates a CRF malfunction. 

User Action: Submit an SPR with the related console dialog and any other pertinent 
information. 
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Unable to open workflle 

Explanation: Possible causes are as follows: 

• The work file device is not mounted. 

• The work file device is write-protected. 

The work file device is assigned to LUN 7 and is normally the device from which CRF was 
installed. 

User Action: Retry the command after ensuring that the device is mounted and write-enabled. 
Work file I/O error 

Explanation: CRF encountered an I/O error while reading or writing data to its work file. 
Possible causes are as follows: 

• Device is full 

• Hardware error 

User Action: If the device capacity has been exceeded, delete unnecessary files to make 
space available. Also, reassign CRF LUN 7 to another Files-11 device. 
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Appendix C 



Data Terminal Emulator (DTE) and the Micro/RSX File 
Transfer Utility (MFT) 

C. 1 Introduction 

A local RSX terminal can log in to and conduct an interactive session with an external computer 
system. This session is established using the Data Terminal Emulator (DTE). The external system 
can be an RSX-llM-PLUS system, a VMS system running VAX-11 RSX, a Professional personal 
computer, or a Micro/RSX system. Once a local RSX terminal is logged in to an external system, 
the external system becomes the host system. The host system views the system running DTE 
as remote. During an interactive session, files can be transferred between the host system and 
the remote system. Files are transferred by using the Micro/RSX File Transfer Utility (MFT). 

The following two conditions must exist for terminal emulation and file transfer to be operational: 

• The two computers must be connected. 

• The DTE software must be installed on the local RSX system, and MFT must be installed 
on the host system. 

Refer to Sections C.2 and C.3 for more detailed information. 

C.2 Connecting Two Computers 

The two computers can be connected either on site or at remote sites through an asynchronous 
serial hne. An RSX system is connected to an on-site external system by a cable and to a remote 
system by modems (DF03, DF112, DF224, and DFAOl) and a telephone line. In either case, 
there is a dedicated line between the two systems that establishes the ports at each end of the 
line, which are assigned specifically for terminal emulation and data transfer. 

A direct hardwired connection between two systems can be established by plugging one end 
of a cable into the communications port in the back of the local system tmit and the other 
end of the cable to a host system. A permanent connection can also be established by using 
a DIGITAL Model H312A null modem cable and two standard EIA RS-232 connectors. When 
the two systems are directly connected with a cable, the terminal characteristics of the port at 
the local RSX system should be set to SLAVE and NOECHO. This prevents the transmission of 
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extraneous noise signals when the port is idle (disconnected from terminal emulation). Noise 
signals can create intersystem echo loops that seriously affect system performance. 

Transmission speed between systems varies, depending on the systems involved. Variations are 
based on the following: 

• Processor type 

• Interface type 

• System load 

• Distance between systems 

• Terminal support (use of higher baud rates requires that the remote system support XON 
/XOFF protocol) 

If XON/XOFF is present, your terminal may run at a speed lower than that of the physical 
connection. For consistent performance, use a baud rate of 2400 for RSX systems. 

Figures C-1 and C-2 show typical configurations. 
Figure C-1: Terminal Emulation witli an On-Slte System 
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Figure C-2: Terminal Emulation with a Remote System 
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In these example configurations, when the local RSX user terminal (TT3) is in terminal emulation, 
the following conditions exist: 

• TT3 is connected to port TT5 using the DTE software. 

• Port TT5 is connected to port TT30 in a PDP-11 system. 

• Port TT5 is a connector on a DZVll. 

• Port TT30 is a connector on a DZll. 

Port TT5 is set by using the following command line: 

For the Monitor Console Routine (MCR): 

>SET /N0ECH0=TT5: [RET] 
>SET /SLAVE=TT5: [M] 

For DIGITAL Command Language (DCL): 

$ SET TERMINAL TT5 : /SLAVE/NOECHO \M\ 

C.3 Location of DTE and MFT 

There are two separate programs that support terminal emulation and file transfer: one resides 
in the local RSX system and the other resides in the host system. DTE, which is installed on 
the local system, establishes the local terminal as an emulated terminal. Establishing terminal 
emulation means connecting a local RSX terminal to an external system so that the local terminal 
can be logged in as a user of the host system. 

The other program is MFT, which interfaces with DTE when file operations are initiated at a 
local terminal. The MFT software is executed on the external computer system (the host) that 
is connected to the local (remote) system. 

DTE and MFT tasks are separate tasks that work together, but they execute on two physically 
different systems. Also, note that all your input is done at a terminal connected to the local 
RSX system. 
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C.4 Establishing Terminal Emulation Using DTE 

Once you have determined that the two specified computers are connected and that both DTE 
and MFT are installed on their respective systems, you can establish terminal emulation. You 
can establish a connection betv^reen a local RSX system and another system with the MCR 
command DTE or the DCL command SET HOST. The following sections describe the formats 
in detail. 

C.4.1 Command Lines 

The MCR command DTE and the DCL command SET HOST/DTE provide options that allow 
you to do the following: 

• Dial out to the remote system through a modem (DF03, DF112, DF224, or DFAOl). 

• Specify the terminal as mute (SLAVE and NOECHO) on termination. 

• Display the version of the DTE task. 

The format of the command line is shown next. 

Format for MCR 

> DTE ttnn:[/option] 

Format for DCL 

$ SET HOST/DTE ttnn: [/option] 

Parameters 

ttnn 

Specifies the RSX device and unit specification of the terminal port used for terminal 
emulation. 
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option 

Specifies one of the following options: 

/DIAL="..." Allows the specification of a dial command string for the modem. The string 
may consist of any of the digits to 9, and one of the following symbols: 

Equal sign {=) 

Asterisk ( • ) 

Hyphen ( - ) 

Uppercase A,B,C,D,P,T, and W 

Lowercase a,b,c,d,p,t, and w 

A space 

Number sign ( # ) 

Left parenthesis 

Right parenthesis 

The equal sign indicates that another dial tone is expected (for example, when 
you dial from an internal telephone system to an outside telephone number). 
The other symbols provide information for the modem being used. See the 
manual that accompanies your modem for more information. 

Note that when you specify /DIAL for a DFAOl modem, the modem 
automatically changes the terminal speed, if necessary. 

/MUTE Specifies whether DTE should alter certain device characteristics prior to exiting. 

The default is to return all of the device characteristics to their original 
states. However, if the device is set NOSLAVE and ECHO, it is possible 
that noise characters can create intersystem echo loops, which can severely 
affect performance. Therefore, it is recommended that either the device be set 
to SLAVE and NOECHO when it is idle (DTE vdll change these characteristics), 
or that the /MUTE option be specified, which will set the device to SLAVE 
and NOECHO when DTE exits. 

/VERSION Displays the version of the DTE task for DCL only. 

/ID Displays the version of the DTE task for MCR only. 

After you establish terminal emulation with either the MCR or DCL command line, you are 
connected to the host system. You can then log in as a user of that system and use the file 
transfer utility (see Section C.5). 

To terminate emulation, log off the host system and press CTRL/P. DTE displays the following 
message: 

7.DTE-S-EMUEXir, Emulation exiting. . . Please wait 

You are then returned to command level execution at the local RSX system. 

Be sure that you log out from the host system before exiting terminal emulation. If you are 
in terminal emulation and press CTRL/P before logging out from the host system, the terminal 
connection is returned to the local RSX system. The host system remains logged in to your 
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account. Under these conditions, if another user initiates terminal emulation, that user will be 
logged in to the host system under your account. 

To use DTE from the system's console terminal, you must first disable the console On-Line 
Debugging Tool (ODT). Both console ODT and DTE use CTRL/P. (For more information on 
ODT, refer to the RSX-llM-PLUS and Micro/RSX Debugging Reference Manual.) The following 
examples show various uses of the MCR command DTE and the DCL command SET HOST 
/DTE. 

Examples for MCR 

>DTE TT5:/MUTE [RET] 

Runs the DTE task, which establishes terminal emulation by connecting your terminal to port 
TT5. When data terminal emulation is terminated, port TT5 is set to SLAVE and NOECHO. 



>DTE TT40: [RET] 

Invokes DTE to establish terminal emulation using terminal TT40. 

>DTE TT50:/DIAL="5550837" [Ml 

Initiates terminal emulation using terminal TT50, after directing the modem to dial the specified 
number and establish a modem connection. 

>DTE TT25:/MUTE [Mi 

Establishes terminal emulation using terminal TT25, and sets the terminal characteristics to 
SLAVE/NOECHO on termination. 

Examples for DCL 

$ SET HOST/DTE TT5:/MUTE \M} 



Runs the DTE task, which establishes terminal emulation by connecting your terminal to port 
TT5. When data terminal emulation is terminated, port TT5 is set to SLAVE and NOECHC). 

$ SET HOST/DTE TT40: fRETl 

Invokes DTE to establish terminal emulation using terminal TT40. 

$ SET HOST/DTE TT50:/DIAL="5550837" [RET| 

Initiates terminal emulation using terminal TT50, after directing the modem to dial the specified 
number and establish a modem connection. 

$ SET HOST/DTE TT25:/MUTE \M] 

Establishes terminal emulation using terminal TT25, and sets the terminal characteristics to 
SLAVE/NOECHO on termination. 
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C.5 Performing File Operations Using IVIFT 

The MFT utility deletes and transfers files by using a local (remote) RSX system, data terminal 
emulation (DTE), and an external (host) system. Special code in the DTE task is used to identify 
and perform file operations requested by the MFT task. To use MFT, you must be using the 
DTE task because the protocol used for the file operations is unique to the two tasks. 

File transfer is performed using an error detection and correction algorithm to ensure data 
integrity. Your local terminal is locked out during file transfer operations to prevent interference 
with the data transfer between the two systems. You are returned to terminal emulation when 
the file operation completes. 

Note 

The speed of file transfer varies with the processor and interface types, system 
load, and software. Support for variable type-ahead buffer size allows for higher 
transfer rates. 

The command syntax used to perform file operations with MFT depends on the command line 
interpreter (CLI) used by the host operating system. If your local terminal is a Professional 300 
Series computer, you may want to use the Professional Forms Interface (PFT) or PFT Command 
Line Format (CFT) instead of MFT. 

To use PFT, use the MCR command MFT /FORM or install MFT as an MCR spawnable task 
with the task name ...PFT. To use CFT, substitute the command MFT for the command PFT on 
all command lines shown in the PRO /Communications User's Guide. (For a complete description 
of PFT and CFT command lines, see the PRO /Communications User's Guide). 

C.5. 1 Command Line for Copying Files 

To copy files from one system to the other, in either direction, use the command line format 
shown next. 

Format for MCR 

> MFT outfile[/REM]=infile[/REM] 

Format for DCL 

$ COPY infile[/REMOTE] outfile[/REMOTE] 

Parameters 

outflle 

Specifies the output file or where the file is being copied to. 

infile 

Specifies the input file or where the file is being copied from. 

/REM 

Specifies the /REM option and indicates the fUe is on your local RSX system and is remote 
to the host system. 
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/REMOTE 

Specifies the /REMOTE option and indicates that the file is on the local RSX system that is 
remote to the host system. The absence of the /REMOTE option indicates the file is on the 
host system. 

For input files, the /REMOTE option indicates that the file resides on the DTE system. For 
output files, the /REMOTE option indicates that the output file should be created on the 
DTE system. 

The following examples show how to copy files. 
Examples for MCR 

>MFT MESSAGE. TXT/REM=HOST. TXT [RET] 

Copies the file HOST.TXT from the host system to the file MESSAGE.TXT on the RSX system. 

>MFT MESSAGE. TXT=RSX. TXT/REM [RET] 

Copies the file RSX.TXT from the RSX system to the file MESSAGE.TXT on the host system. 

Examples for DCL 

$ COPY INFILE.DAT OUTFILE . DAT/REMOTE \M1 

Copies the file INFILE.DAT from the host (MFT) system into OUTFILE.DAT on the remote 
(DTE) system. 

$ COPY INFILE. DAT/REMOTE OUTFILE.DAT IM] 

Copies the file INFILE.DAT from the remote (DTE) system into OUTFILE.DAT on the host 
(MFT) system. 

C.5.2 Command Line for Deleting Files 

To delete files using MFT, use the format shown next. 

Format for MCR 

> MFT delfile/DE[/REM] 

Format for DCL 

$ DELETE delfile[/REMOTE] 

Parameters 

delflle 

Specifies the name of the file to be deleted. The file name cannot include wildcards. 

/DE 

Specifies the file is to be deleted. 

/REM 

Specifies the file is on the RSX system remote to the host system. Do not specify the /REM 
option if the file is on the host system. 
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/REMOTE 

Specifies the /REMOTE option and indicates that the file is on the local RSX system that is 
remote to the host system. The absence of the /REMOTE option indicates the file is on the 
host system. When using the DELETE command with the /REMOTE option, the file to be 
deleted should be deleted on the DTE system. 

The following examples show how to delete files. 
Example for MCR 

>MFT MESSAGE. TXT/DE [RfT] 

Deletes the file MESSAGE.TXT from the host system. 

Example for DCL 

$ DELETE FILE. DAT/REMOTE \Mi 

Deletes the file FILE.DAT on the remote (DTE) system. 

C.5.3 Example of File Transfer Session 

An MCR example of a file transfer session that uses DTE and MFT is as follows: 

>DTE TT5: [RETI 
>HELLD [RET] 

>USERNAME: usemame [RET] 
>PASSWORD: <password> ^ 



>MFT MESSAGE. TXT=MICRO. TXT/REM [RET] 

XDTE-S-MFTINIT, File operation initiated 

XDTE-S-MFTCOMP . File operation complete 

(The cursor may be at the beginning of the last message. To 
continue the operation, press RETURN.) 

fRETl 



MFT> fCTRi7z1 
>BYE [RET] 



> I CTRL/PI 

XDTE-S-EMUEXIT, Emulation exiting. . . Please wait 



C.6 Messages 

The following sections list and describe the messages produced by DTE and MFT. 
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C.6. 1 DTE Messages 

The following messages are produced by DTE. Some messages also include a 6-character octal 
field enclosed in parentheses. This field provides additional internal information regarding the 
cause of the error, but it is generally not useful to you unless the information is also mentioned 
in the message description. 

7DTE-F-DEVTYPE, Illegal device type for DTE 

Explanation: DTE assigned the specified emulation device and found that it was not a 

terminal. 

User Action: No user action is required. DTE can be used only on terminal devices. 

%DTE-S-DF03SEQ, Dialing... Please hold 

Explanation: You specified the DTE /DIAL option and DTE is attempting to establish a 
connection by using a modem. 

User Action: No user action is required. Your terminal is locked out until the modem 
responds with either success or failure. 

7DTE-F-DF03TMO, Telephone connection failure due to timeout 

Explanation: DTE sent the dial sequence specified by the /DIAL option, and the modem did 
not respond within 40 seconds. 

User Action: No user action is required. DTE will attempt to hang up the line and then exit 
with an error status. 

%DTE-S-DIALHNG, Dialup line hung up 

Explanation: DTE is attempting to hang up the specified emulation terminal that is connected 
to a modem. It may or may not have succeeded in hanging up. 

User Action: No user action is required. This is an informational message. 

%DTE-I-DTETVER, Data Terminal Emulator Version x.y ([dd-mmm-yy]) 

Explanation: You specified the /IDENTIFICATION option in the command line, so DTE is 
displaying its version number. 

User Action: No user action is required. This is an informational message. 

%DTE-S-EMUEXIT, Emulation exiting... Please wait 

Explanation: You pressed CTRL/P at your terminal, and DTE has begun exit processing. 
Your terminal is locked out, all DTE I/O processing is being completed, and all device 
characteristics are being restored. 

User Action: No user action is required. This operation takes approximately 5 seconds. 
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7DTE-F-ERDDCMP, Transmission [DDCMP] failure (xxxxxx) 

Explanation: During DTE/MFT file transfer, a DDCMP error occurred that could not be 
corrected after trying several times. The physical (emulation) terminal lines are producing 
too many errors for a file operation to be performed. Reasons for this type of error are as 
follows: 

• Baud rates are too high. 

• The systems are too far apart (the physical cable is too long). 

• The system lacks the required terminal support. 

• There is some electrical interference (noise) along the physical connection (because of a 
bad telephone connection or heavy electrical equipment). 

User Action: Determine the reason for the error; correct that error, if possible; and try the 
operation again. 

7DTE-F-FATALER, internal error (xxxxxx) 

Explanation: DTE/MFT has encountered an unexpected internal condition. This message 
indicates an error in the local file operations server within the DTE task. 

User Action: Reenter the command. If the error persists, submit a DIGITAL Software 
Performance Report (SPR). 

%DTE-S-IVIFTCOMP, File operation complete 

Explanation: A DTE/MFT file operation has completed, and control has been returned to 
your terminal. If the operation has completed in failure, then this message is preceded by 
an error message showing the cause of the file operation failure. 

User Action: No user action is required. 
%DTE-S-MFTINIT, File operation initiated 

Explanation: DTE has received the communications protocol ("handshake") sequence from 
the MFT task on the other system. DTE invokes the file transfer server to provide local 
support for the operation being initiated on the remote system. 

User Action: No user action is required. Your terminal is locked out until the operation 
completes. 

7DTE-F-IVIODERR, Unable to determine modem type 

Explanation: DTE has either failed to receive a response from the modem or is unable to 
determine the type of modem (DF03, DF112, DF224, or DFAOl) in use. This message may 
indicate faulty hardware. 

User Action: Check to see that the modem is properly connected and that the modem 
switches and port characteristics are properly set. 
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7DTE-F-MSGFORM, Message format error (xxxxxx) 

Explanation: The version of the MFT file server within the DTE task is not compatible with 
the version of the MFT task on the remote system. This may be caused by an error in the 
remote MFT task or by an incompatibility of releases of DTE and MFT. 

User Action: No user action is required. 

7DTE-F-NOTSELD, Terminal line not selected 

Explanation: This is an internal error and indicates that the Logical Unit Number (LUN) has 
been lost. 

User Action: Reenter the command. If the error persists, submit an SPR. 

%DTE-S-PHONEOK. Telephone connection establistied 

Explanation: DTE sent the dial sequence specified by the /DIAL option, and the modem 
responded with success (it returned the character A). 

User Action: No user action is required. The connection to the remote system has been 
successfully established. 

7DTE-F-PHONERR, Failure to establisti telephione connection 

Explanation: DTE sent the dial sequence specified by the /DIAL option, and the modem did 
not respond with success. 

User Action: No user action is required. DTE will hang up the line and then exit with error 
status. 

7DTE-F-PORTSEL. Assignment failure on specified device 

Explanation: DTE was unable to assign and attach the specified emulation terminal device. 
The device may be attached by another user, or it may be an inappropriate device type for 
emulation. 

User Action: Wait for the device to be detached or reenter the command with an appropriate 
device type specified. 

7DTE-F-REJOPER, Operation rejected (xxxxxx) 

Explanation: The file operations server within the DTE task cannot perform the operation 
requested by the MFT task executing on the remote system. Either the DTE task lacks the 
required support, or the version of the remote MFT task does not match the version of DTE 
being used on the local system. 

User Action: No user action is required. 

7DTE-F-RMSRERR. Remote RMS-1 1 error (xxxxxx) 

Explanation: An error occurred during the attempt to perform the file operation. The RMS-1 1 
error code (in octal) is displayed within the paired parentheses. 

User Action: No user action is required. 
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7DTE-F-SYNLOST, Synchronization lost (xxxxxx) 

Explanation: Synchronization has been lost between the local DTE and the remote MFT 
tasks. This may be related to the baud rate of the emulation terminal lines or the systems' 
loads. 

User Action: Retry the operation. 
7DTE-F-SYNXERR, Syntax error 

Explanation: The syntax of the DTE command either was not appropriate or did not fit the 
documented syntax. 

User Action: Enter the correct command. 

7DTE-F-UNSPROT, Unsupported protocoi operation (xxxxxx) 

Explanation: The version of DDCMP being used by the local DTE file operations server and 
the remote MFT task are not compatible. The versions of DTE and MFT are not compatible, 
and the requested operation cannot be performed. 

User Action: No user action is required. 

C.6.2 MFT Messages 

The following messages are produced by MFT. Some messages also include a "..." field. 
This indicates that all or part of the command line will be displayed with the message. 

?iVIFT-F-BADOPER. Illegoi option specified: ... 

Explanation: A nonexistent or illegal option was specified on the command line, or the 
option or options selected are out of context. 

User Action: No user action is required. 
7MFT-F-COIVIFILE, Unable to open specified command file 

Explanation: MFT was unable to access the specified command file. No details as to the 
reason for the failure are available. Typical reasons for this message are: file not found, 
protection violations, and so on. 

User Action: No user action is required. 
7MFT-F-FOPFAIL, File operation foiled 

Explanation: The particular file operation specified could not be performed. There are many 
possible causes for the failure. Typically, this message is produced when MFT is unable to 
S5mchronize with the file operations server it requests DTE to invoke. Reasons for this type 
of error are as follows: 

• Baud rates are too high. 

• The systems are too far apart (the physical cable is too long). 

• The system lacks the required terminal support. 
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• There is some electrical interference (noise) along the physical connection (because of a 
bad telephone connection or heavy electrical equipment). 

User Action: No user action is required. 

?MFT-F-ILLNODE, Illegal node combination: ... 

Explanation: The MFT command string specifies both file specifications on the same system. 
Either /REM appears on both file specifications or does not appear on either specification. 
Each file specification must specify a different system. 

User Action: Specify the /REM option with one file specification only and reenter the 
command line. 

7MFT-F-LINELEN, Command line too long 

Explanation: The command line specified was too long for the command buffer. Because 
some of the command may have been lost, the entire command is considered invalid. 

User Action: Enter a shorter command line. 

?MFT-F-SPECERR, Error In file specification: ... 

Explanation: One or both of the file specifications supplied are in error. File specification 
syntax is limited to the standard RSX-11 format, which is as follows: 

device : [uic] filename . type ; version 

User Action: Use valid file specifications and reenter the command line. 

7MFT-F-SYNXERR, Syntax error: ... 

Explanation: The syntax of the command line specified is in error. Possible causes may be 
illegal options, missing input or output file specifications, or an error in the file specification 
syntax. 

User Action: Use the correct sjmtax and reenter the command line. 
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/CB switch 

CMP utility, 4-3 
/CD switch 
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Change command 
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Close command 
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Data Terminal Emulator 

See DTE 
Data transfer 
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DSC utility, 6-18 

FLX utility, 8-1 
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DMP utility, 5-4 
/DD switch 
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/DD switch (cont'd.) 

PIP utility, 12-10 
Delete & Print command 
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DELETE command, C-9 

/REMOTE option, C-8 
Delete command 

EDI editor, 7-21 
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BRU utility, 3-14 
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command 
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support 
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compressing, 6-4 
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copying 
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command line, 5-2, A-8 
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DTE command 
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parameters, C-4 
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Echo loops 
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Erase command 

EDI editor, 7-23 
/ERL switch 

FMT utility, 9-3 
/ERRORS qualifier 

BRU utility, 3-16 
ESCAPE key 

EDI editor, 7-23 
/EXCLUDE qualifier 

BRU utility, 3-16 
Exit & Delete command 

EDI editor, 7-24 
Exit command 

EDI editor, 7-23 
/EX switch 

LBR utility, 10-19 

PIP utUity, 12-15 
/EXTEND qualifier 

BRU utility, 3-16 
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/FA switch 

FLX utility, 8-6 
/FB switch 

FLX utility, 8-6 
/FC switch 

FLX utility, 8-8 
/FF switch 

CMP utility, 4-3 
File 

appending, 12-8 
comparing, 4-1 
cop5dng 

BRU utility, 3-1 

DSC utility, 6-1 

Files-11, 12-35 

PIP utility, 12-35 

using MFT, C-7 
creating, 7-2 
deleting, 12-11 

using DELETE command, C-9 

using MFT, C-8, C-9 
displaying 

block number, 12-19 
dumping, 5-1 
editing, 7-1 
FORTRAN direct access 

See FLX utility 
index 

listing contents, 14-5 
library, 10-1 
listing 

FLX utility, 8-7 

LBR utility, 10-22 

PIP utility, 12-18 
merging, 12-36 
ownership 

PIP utility, 12-37 
protection 

Files-11, 12-22 
purging, 12-24 
recovering lost file, 14-5 
renaming, 12-25 
saving 

BRU utility, 3-1 

DSC utility, 6-1 
specification, 1-4 
spooling, 12-30 
transfer 

sample session, C-9 
transferring, 8-1, 8-4, C-3, C-7 



FUe 

transferring (cont'd.) 

DOS-11, 8-4 

RT-11, 8-4 

using VAX-11 RSX systems, C-1 

using MFT, C-7 

using professional personal computer 
systems, C-1 
truncating, 12-32 
universal library 

See Universal library file 
updating 

PAT utility, 11-1 
PIP utility, 12-34 
SLP utility, 13-1 
ZAP utility, 15-1 
validating contents, 11-8 
File command 

EDI editor, 7-24 
File Compare Utility 

See CMP utility 
File Dump Utility 
See DMP utility 
FUes-11 file 
copying, 12-35 

FLX utility, 8-2 
protection, 12-22 
verifying structure, 14-1 
File Structure Verification Utility 

See VFY utility 
File Transfer Utility 

See FLX utility 
Find command 

EDI editor, 7-24 
/FI switch 

DMP utility, 5-5 
PIP utUity, 12-16 
FLX utility 
cassette, 8-13 

input file, 8-14 
multivolume support, 8-13 
output file, 8-13 
TA11/TU60 support, 8-13 
command line, 8-3, A-15 
control switches, 8-4 
device support, 8-2 
DOS-11 volume, 8-9 
deleting, 8-10 
directory listing, 8-9 
initializing, 8-10 
valid, 8-1 
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FLX utility (cont'd.) 

file 

deleting, 8-7 

Files-11, 8-2 

processing, 8-7 

specifying, 8-3 
FORTRAN direct access file, 8-16 
messages, 8-16 

error, 8-17 

informational, 8-17 

warning, 8-17 
paper tape support, 8-15 
RT-11 volume, 8-10 

deleting, 8-11 

directory listing, 8-11 

initializing, 8-12 

valid, 8-2 
switches 

/BL, 8-7 

/BS, 8-7 

/CO, 8-7 

/DE, 8-7 

default, 8-4 

/DI, 8-7 

/DNS, 8-8 

/DO, 8-4 

/FA, 8-6 

/FB, 8-6 

/FC, 8-8 

/ID, 8-8 

/IM, 8-6 

/LI, 8-8 

/NU, 8-8 

/RS, 8-4 

/RT, 8-4 

/RW, 8-8 

/SP, 8-8 

/UI, 8-8 

/VE, 8-8 

/ZE, 8-9 
transfer mode switches, 8-4 
volume 

directory listing, 8-7 

file deletion, 8-7 

file transfer, 8-5 

formatting, 8-4 

initializing, 8-2 
volume format switches, 8-4 
wildcard, 8-3 
FMT utility 

command line, 9-1, A-17 
device support, 9-7 



FMT utility (cont'd.) 
error messages, 9-10 
initiating, 9-1 
operation mode, 9-5 
operation range, 9-7 
switches 

/BAD, 9-3 
/DENS, 9-3 
/ERL, 9-3 
/MAN, 9-4 
/NOVE, 9-4 
/OVR, 9-4 
/VE, 9-5 
/WLT, 9-5 
/@Y, 9-4 
terminating, 9-2 
Form Feed command 

EDI editor, 7-25 
/FO subswitch 

PIP utility, 12-37 
/FR switch 

PIP utility, 12-17 
VFY utility, 14-4 
/FU subswitch 

PIP utility, 12-19 
/FU switch 

LBR utiUty, 10-22 

H 



/HD switch 

/AL subswitch, 14-4 
DMP utility, 5-5 
VFY utility, 14-4 

/HEADERS qualifier 
BRU utility, 3-16 

/HF switch 

DMP utility, 5-5 

/HX switch 

DMP utility, 5-5 



/IDENTIFICATION qualifier 

BRU utility, 3-17 
/ID option 

DTE command, C-5 
/ID switch 

DMP utility, 5-5 

FLX utility, 8-8 

PIP utility, 12-17 

VFY utility, 14-5 
/IMAGE qualifier 
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/IMAGE qualifier (cont'd.) 

BRU utility, 3-17 

option 

RESTORE, 3-17 
SAVE, 3-17 
/IM switch 

FLX utility, 8-6 
Index file 

listing contents, 14-5 
Indirect command file, 1-9 

BAD utility, 2-6 

SLP utility, 13-8 

ZAP utility, 15-4 
Indirect command file switch 

FMT utility, 9-4 
/INITIALIZE qualifier 

BRU utility, 3-18 
Insert command 

EDI editor, 7-25 
/IN switch 

LBR utility, 10-20 
Intersystem echo loops, C-2, C-5 
/INVOLUME qualifier 

BRU utility, 3-18 

K 

K command 

ZAP utility, 15-17 
Kill command 

EDI editor, 7-26 



LBR utility 

combining library function, 10-32 
command line, 10-10, A-17 

default, 10-11 
library file 

creating, 10-13 

deleting, 10-15 

format, 10-2 

listing, 10-22 

module 

inserting, 10-21 
replacing, 10-24 

spooling, 10-29 
messages, 10-32 

diagnostic, 10-33 

fatal, 10-34 
restriction, 10-10 
switches 

/CO, 10-12 



LBR utility 

switches (cont'd.) 

/CR, 10-13 
/DE, 10-15 
/DF, 10-16 
/DG, 10-17 
/EP, 10-18 
/EX, 10-19 
/FU, 10-22 
/IN, 10-20 
/LE, 10-22 
/LL 10-22 
/MH, 10-23 
/RP, 10-24 
/SP, 10-29 
/SS, 10-29 
/SZ, 10-30 
universal library file 
module 

inserting, 10-21 
replacing, 10-27 
/LB switch 

DMP utility, 5-6 
/LC switch 

DMP utility, 5-6 
/LENGTH qualifier 
BRU utility, 3-19 
/LE switch 

LBR utility, 10-22 
Librarian Utility Program 

See LBR utility 
Library file 

See LBR utility 
/LIM switch 

DMP utility, 5-6 
Line Change command 

EDI editor, 7-26 
Line Text Editor 
See EDI editor 
Listing file 

FLX utility, 8-7 
PIP utility, 12-18 
List on Pseudo Device command 

EDI editor, 7-26 
List on Terminal command 

EDI editor, 7-27 
/LI switch 

BAD utility, 2-4 
CMP utility, 4-3 
FLX utility, 8-8 
LBR utility, 10-22 
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/LI switch (cont'd.) 
PIP utility, 12-18 
subswitches 
/BR, 12-19 
/FU, 12-19 
/TB, 12-19 
VFY utility, 14-5 
ZAP utility, 15-2 
/LN switch 

CMP utility, 4-3 
Locate command 

EDI editor, 7-27 
Location addressing 
ZAP utility, 15-7 
/LO switch 

VFY utility, 14-5 
/LW switch 

DMP utility, 5-6 

M 



MACRO-11 

source file 

cross-reference symbols 
CRF utility, B-2 
Macro Call command 

EDI editor, 7-28 
Macro command 

EDI editor, 7-28 
Macro Execute command 

EDI editor, 7-29 
Macro Immediate command 

EDI editor, 7-30 
Magnetic tape 

See Tape 
/MAN switch 

BAD utility, 2-4 

FMT utility, 9-4 
/MAXIMUM qualifier 

BRU utility, 3-19 
/MB switch 

CMP utility, 4-3 
/MD switch 

DMP utility, 5-6 
Messages 

DTE, C-10 

EDI editor, 7-53 

MFT, C-13 

utility 

BAD, 2-9 
BRU, 3-39 
CMP, 4-8 



Messages 

utility (cont'd.) 

CRF, B-6 

DMP, 5-10 

DSC, 6-21 

FLX, 8-16 

LBR, 10-32 

PAT, 11-8 

SLP, 13-20 

VFY, 14-9 
/ME switch 

PIP utility, 12-21, 12-36 
subswitches 

/BL, 12-37 

/CO, 12-37 

/FO, 12-37 

/NV, 12-37 

/SU, 12-37 
MFT 

copying files, C-7 
deleting files, C-8 
dependence on CLI, C-7 
file transfer algorithm, C-7 
installing for use with PFT, C-7 
messages, C-13 

performing file operations, C-7 
requirements, C-1 
use with DTE, C-7 
using MCR command sjmtax, C-7 
using with Professional 300 Series, C-7 
MFT/FORM command, C-7 
MFT command, C-7 
deleting files, C-9 
/DE option, C-8 
example, C-8, C-9 
option 

/DE, C-8 

/REM, C-7, C-8 
/MH switch 

LBR utility, 10-23 
Micro/RSX File Transfer Utility 

See MFT 
Modem 

connecting computer systems, C-1 

dial command string, C-5 

null cable, C-1 
/MOUNTED qualifier 

BRU utility, 3-20 
/MUTE option 

command 

SET HOST/DTE, C-5 
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N 



/NEW_VERSION qualifier 

BRU utility, 3-20 
Next & Print command 

EDI editor, 7-31 
Next command 

EDI editor, 7-30 
/NM switch 

PIP utUity, 12-21 
/NOECHO option 

SET TERMINAL command, C-3 
/NOINITIALIZE qualifier 

BRU utility, 3-21 
/NOPRESERVE qualifier 

BRU utility, 3-21 
/NOSUPERSEDE qualifier 

BRU utility, 3-21 
/NOVE switch 

FMT UtUity, 9-4 
/NS switch 

SLP UtUity, 13-15 
/NU switch 

FLX UtUity, 8-8 
/NV subswitch 

PIP UtUity, 12-37 



O 



Object module 

patching, 11-1 

storing in library, 10-20 
Object Modvde Patch Utility 

See PAT utUity 
O command 

ZAP UtUity, 15-18 
/OCT switch 

DMP UtUity, 5-6 
ODT 

ZAP UtUity, 15-1 
On-Line Debugging Tool 

See ODT 
Open Secondary command 

EDI editor, 7-31 
Operator 

See SLP utUity 
Output On/Off command 

EDI editor, 7-32 
/OUTVOLUME qualifier 

BRU UtUity, 3-21 
Overlay command 

EDI editor, 7-32 



/OVR switch 
BAD UtUity, 2-5 
FMT UtUity, 9-4 

P 



Page command 

EDI editor, 7-33 
Page Find command 

EDI editor, 7-33 
Page Locate command 

EDI editor, 7-33 
Paste command 

EDI editor, 7-34 
/PAT switch 

BAD utility, 2-5 
PAT UtUity 

checksum, 11-8 

Checksum switch 
See /CS switch 

command line, 11-1, A-24 

/CS switch, 11-2, 11-8 

file 

correction, 11-4 
input, 11-4 

messages, 11-8 
error, 11-9 
informational, 11-9 

TaskBuUder, 11-5 

validating file content, 11-8 
Percent sign ( % ) 

See WUdcard 
Peripheral Interchange Program 

See PIP UtUity 
PFT 

using, C-7 
PFT Command Line Format 

See CFT 
PIP UtUity 

command functions, 12-35 

concatenating, 12-39 

copying FUes-1 1 file, 12-35 

file control, 12-39 
command line, 12-1, A-24 

ampersand (&), 12-39 

switch placement, 12-5 
copy command 

subswitches, 12-37 
file 

control, 12-3 

deleting, 12-11 

listing, 12-18 
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PIP utility 
file (cont'd.) 

merging, 12-36 

protecting, 12-22 

purging, 12-24 

renaming, 12-25 

spooling, 12-30 
file specification, 12-2 

default, 12-2 to 12-3 

wildcard, 12-7 
merge 

subswitches, 12-37 
messages 

error, 12-40 

error code, 12-49 

format, 12-40 
subswitches 

copy command, 12-37 

description, 12-19 

file control, 12-39 

merge, 12-37 

placement in command line, 12-5 
switches 

/AP, 12-8 

/BS, 12-9 

/CD, 12-10 

/DD, 12-10 

/DE, 12-11 

/DF, 12-12 

/EN, 12-13 

/EOF, 12-14 

/EX, 12-15 

/FI, 12-16 

/FR, 12-17 

/ID, 12-17 

/LI, 12-18 

/ME, 12-21, 12-36 

/NM, 12-21 

/PR, 12-22 

/PU, 12-24 

/RE, 12-25 

/RM, 12-27 

/RW, 12-28 

/SB, 12-29 

/SP, 12-30 

/SR, 12-31 

/SS, 12-29 

/TD, 12-32 

/TR, 12-32 

/UF, 12-33 

/UN, 12-34 

/UP, 12-34 



PIP utility (cont'd.) 

UFD creation, 12-33 

wildcard, 12-7 
Port 

See Communications port 
/POSITION qualifier 

BRU utility, 3-22 
Print command 

EDI editor, 7-34 
Professional 300 Series computer 

using with MFT, C-7 
Professional Forms Interface 

See PFT 
Professional personal computer 

file transfer using MFT, C-1 
Protection code 

file, 12-19 
/PROTECTION qualifier 

BRU utility, 3-22 
/PR switch 

PIP utility, 12-22 
/PU switch 

PIP utility, 12-24 

R 

/R5 switch 

DMP utility, 5-7 
R command 

ZAP utility, 15-19 
/RC switch 

DMP utility, 5-6 

VFY utility, 14-6 
Read command 

EDI editor, 7-34 
Read-Only switch 

See /RO switch 
/REM option 

command 

MFT, C-7, C-8 

MFT command, C-8 
/REMOTE option 

command 

COPY, C-8 
DELETE, C-8 
Renew command 

EDI editor, 7-35 
/RE switch 

PIP utility, 12-25 

VFY utiUty, 14-6 
/RETRY switch 

BAD utility, 2-5 
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RETURN key command 

EDI editor, 7-35 
Retype command 

EDI editor, 7-36 
/REVISED quaUfier 

BRU utility, 3-23 
/REWIND qualifier 

BRU utility, 3-24 
/RM switch 

PIP utility, 12-27 
/RO switch 

ZAP utility, 15-2, 15-5 
/RP switch 

LBR utility, 10-24 
/RS switch 

FLX utility, 8-4 

SLP utility, 13-16 
RT-11 

device support, 8-2 

file transferring, 8-4 

volume 

deleting, 8-11 
directory listing, 8-11 
initializing, 8-12 
/RT switch 

FLX utility, 8-4 
/RW switch 

DMP utility, 5-7 

DSC utility, 6-15 

FLX utility, 8-8 

PIP utility, 12-28 



Save command 

EDI editor, 7-36 
/SB switch 

DMP utility, 5-7 

PIP utility, 12-29 
/SD switch 

PIP utility, 12-29 
Search & Change command 

EDI editor, 7-37 
Select Primary command 

EDI editor, 7-37 
Select Secondary command 

EDI editor, 7-38 
SET HOST/DTE command, C-4 

example, C-6 

format, C-4 

option 

/DIAL, C-5 



SET HOST/DTE command 
option (cont'd.) 

/MUTE, C-5 

/VERSION, C-5 
parameters, C-4 
SET TERMINAL command, C-3 
option 

/NOECHO, C-3 

/SLAVE, C-3 
/SF swdtch 

DMP utility, 5-7 
Size command 

EDI editor, 7-38 
/SLAVE option 

SET TERMINAL command, C-3 
SLP utility 

audit trail, 13-16 

changing value, 13-18 

deleting, 13-20 

setting 

length, 13-17 
position, 13-17 

suppressing, 13-19 
calculating checksum, 13-2 
command line, A-32 
edit commands, 13-5 
file 

input, 13-2 

listing, 13-3 

output, 13-3 

processing, 13-3 

source 

creating, 13-14 
updating, 13-9 
indirect command file, 13-8 
initiating (invoking), 13-1 
messages, 13-20 

diagnostic error, 13-21 

fatal error, 13-23 

informational, 13-21 
operator, 13-9 
switches 

/AU, 13-15 

/BF, 13-15 

/CM, 13-15 

/CS, 13-15 

/DB, 13-15 

/NS, 13-15 

/RS, 13-16 

/SP, 13-16 

/SQ, 13-16 

/TR, 13-16 



Index-13 



/SL switch 

CMP utility, 4-3 
Source file 

See SLP utility 
Source Language Input Program 

See SLP utility 
Spool 

file, 12-30 

library file, 10-29 
/SP switch 

CMP utility, 4-3 

CRF utility, B-3 

DMP utility, 5-7 

FLX utility, 8-8 

LBR utility, 10-29 

PIP utility, 12-30 

SLP utility, 13-16 
/SQ switch 

SLP utility, 13-16 
/SR switch 

PIP utiHty, 12-31 
/SS switch 

LBR utility, 10-29 
Standalone BRU 

See BRU utility 
/SUPERSEDE qualifier 

BRU utility, 3-24 
/SU subswitch 

PIP utility, 12-37 
/SZ switch 

LBR utility, 10-30 



Tab On/Off command 

EDI editor, 7-38 
Tape 

backing up, 3-1 

comparing, 6-13 

conventional backup, 3-3 

copying, 3-1 

formatting, 8-4 

full backup, 3-4 

mounting, 3-2 

restoring, 3-1 

selective backup, 3-4 

setting block size, 12-9 

transferring data, 6-19 

verifying, 14-1 
/TAPE-LABEL qualifier 

BRU utUity, 3-24 



Task 

patching image file, 15-1 
Task/File Patch Program 

See ZAP utility 
/TB subswitch 

PIP utility, 12-19 
/TB switch 

CMP utility, 4-4 
/TD switch 

PIP utility, 12-32 
Telephone 

dial command string, C-5 
Terminal 

baud rate for RSX systems, C-2 

establishing port's for data transfer, C-1 

lock out during file transfer, C-7 

setting characteristics for, C-1 

type-ahead buffer, C-7 
Terminal emulation 

establishing, C-3 
using DCL, C-4 

terminating, C-5 
Terminal line 

asynchronous, C-1 

variations in transmission speed, C-2 
TKB 

PAT utility, 11-5 
Top command 

EDI editor, 7-39 
Top of File command 

EDI editor, 7-39 
/TR switch 

PIP utility, 12-32 

SLP utility, 13-16 
Type-ahead buffer, C-7 
Type command 

EDI editor, 7-40 

U 

UFD 

creating, 12-33 
/UFD qualifier 

BRU utility, 3-24 
/UF switch 

PIP utility, 12-33 
/UI switch 

FLX utility, 8-8 
Universal libraty file 

module 

inserting, 10-21 
replacing, 10-27 
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Unsave command 

EDI editor, 7-40 
/UN switch 

PIP utility, 12-34 
/UPD switch 

BAD utility, 2-5 
Uppercase On/Off command 

EDI editor, 7-40 
/UP switch 

VFY utility, 14-7 
/UP switch 

PIP utility, 12-34 
User File Directory 

SeeUFD 
Utility 

command line general format, 1-3 

editing, 1-2 

file manipulation, 1-3 

file specification 
default, 1-4 
format, 1-4 

indirect command file, 1-9 

invoking, 1-6 
DCL, 1-6 
installed, 1-7, 1-8 
MCR, 1-6 

listed, 1-1 

program maintenance, 1-2, 1-3, 15-1 

programming, 1-2, 1-3 

volume maintenance, 1-2, 1-3 

V 

VAX-11 RSX 

file transfer using MFT, C-1 
/VB switch 

CMP utility, 4-4 
V command 

ZAP utility, 15-19 
Verification 

device, 2-7 

file structure, 14-1 

task image file content 
See ZAP utility 
Verify On/Off command 

EDI editor, 7-42 
/VERIFY qualifier 

BRU utility, 3-25 
/VERIFY switch 

DSC utility, 6-17 
/VERSION option 

command 



/VERSION option 
command (cont'd.) 

SET HOST/DTE, C-5 
/VE switch 

FLX utility, 8-8 
FMT utility, 9-5 
VFY utility 

command line, 14-2, A-33 
messages, 14-9 

error, 14-11 

format, 14-9 
operation mode, 14-7 
switches 

/DE, 14-3 

/DV, 14-3 

/FR, 14-4 

/HD, 14-4 

/AL subsvwtch, 14-4 

/ID, 14-5 

/LI, 14-5 

/LO, 14-5 

/RC, 14-6 

/RE, 14-6 

/UP, 14-7 
validity check, 14-7 
Volume 

backing up, 3-1 

See also BRU utility 

See also DSC utility 
compressing, 6-4 
directory listing, 8-7 
displaying free space 

PIP utility, 12-17 

VFY utility, 14-4 
examining data, 5-1 
file 

deleting, 8-7 

recovering lost, 14-5 

transferring, 8-5 
formatting 

FLX utility, 8-4 

FMT utility, 9-1 
initializing 

BRU utility, 3-18 

FLX utility, 8-2 
listing File ID, 14-5 
locating bad block 

BAD utility, 2-1 

FMT utility, 9-1 

VFY utility, 14-6 
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Volume (cont'd.) 
recovering 

lost block, 14-6 
lost file, 14-5 
space, 6-4 
restoring, 3-1 
verifying, 14-1 
block, 14-6 

W 



/WD switch 

DMP utility, 5-7 
Wildcard 

asterisk (*), 3-7, 3-9, 12-7 

file specification 

BRU utility, 3-7, 3-9 
FLX utility, 8-3 
PIP utility, 12-7 

percent sign (%), 12-7 
/WINDOWS qualifier 

BRU utility, 3-25 
/WLT switch 

FMT utility, 9-5 
Write command 

EDI editor, 7-43 

X 



X command 

ZAP utility, 15-16 
XON/XOFF protocol, C-2 

Y 



/@Y switch 
FMT utility, 9- 

z 



ZAP utility 

address boundary 

displajning, 15-4 
addressing locations, 15-7 
addressing mode, 15-6 
arithmetic operators 

asterisk ( * ), 15-9 

minus sign (-), 15-9 

plus sign (+), 15-9 
command 

carriage return, 15-7 

general-purpose, 15-7, 15-16 

open/dose location, 15-7, 15-12 
command line, 15-7, A-34 



ZAP utility (cont'd.) 

displaying overlay segment bounderies, 

15-2 
element separators 

colon (:), 15-10 

comma (,), 15-10 

semicolon (;), 15-10 
error messages, 15-26 
example, 15-20 
indirect command file, 15-4 
initiating (invoking), 15-2 
location 

addressing, 15-5 

closing, 15-13 

contents 

changing, 15-13 
displaying, 15-13 
verifying, 15-19 

opening, 15-13 

specifying, 15-10 
ODT online debugger, 15-1 
open and close commands 

apostrophe (' ), 15-12 

at sign (@), 15-12 

backslash (\), 15-12 

circumflex (" ), 15-12 

left angle bracket, 15-12 

percent sign (%), 15-12 

quotation marks ("), 15-12 

RETURN key, 15-12 

right angle bracket, 15-12 

slash (/), 15-12 

underscore (_), 15-12 
operating mode, 15-5 
register 

constant, 15-8 

format, 15-8 

quantity, 15-8 

relocation, 15-8 

setting value, 15-19 
relocation biases, 15-5 
switches 

/AB, 15-2, 15-5 

/LI, 15-2 

/RO, 15-2, 15-5 
task image file, 15-3 

instruction and data space, 15-4 

multiuser, 15-3 

resident library, 15-4 
terminating, 15-2 
/ZE switch 

FLX utiUty, 8-9 
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READER'S 
COMMENTS 



Your comments and suggestions are welcome and will help us in our 
continuous effort to improve the quality and usefulness of our documentation 
and software. 

Remember, the system includes information that you read on your terminal: 
help files, error messages, prompts, and so on. Please let us know if you have 
comments about this information, too. 

Did you find this manual understandable, usable, and well organized? Please make suggestions for 
improvement. 



Did you find errors in this manual? If so, specify the error and the page number. 



What kind of user are you? 



Programmer 



Nonprogrammer 



Years of experience as a computer programmer/user: 



Name 

Organization 

Street 

City 



Date_ 



_ State 

or Country 



.Zip Code. 
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